@janga/norna 0.7.23 → 0.7.25

package/scripts/lib/semantic-callouts.mjs

@@ -0,0 +1,128 @@
+export const semanticCalloutTypes = Object.freeze([
+	'NOTE',
+	'TIP',
+	'IMPORTANT',
+	'WARNING',
+	'CAUTION',
+	'DANGER',
+]);
+
+const semanticCalloutTypeSet = new Set(semanticCalloutTypes);
+const markerPattern = /^\[!([A-Za-z][A-Za-z0-9-]*)\]([^\n]*)(?:\n|$)/;
+
+const hasMeaningfulContent = (node) => {
+	if (!node || typeof node !== 'object') return false;
+	if ('value' in node && typeof node.value === 'string') return node.value.trim().length > 0;
+	if (node.type === 'image') return Boolean(node.alt);
+	return Array.isArray(node.children) && node.children.some(hasMeaningfulContent);
+};
+
+export const getSemanticCalloutMarker = (node) => {
+	if (node?.type !== 'blockquote') return null;
+	const firstParagraph = node.children?.[0];
+	const firstText = firstParagraph?.type === 'paragraph' ? firstParagraph.children?.[0] : null;
+	if (firstText?.type !== 'text') return null;
+
+	const match = firstText.value.match(markerPattern);
+	if (!match) {
+		return firstText.value.startsWith('[!')
+			? { malformed: true, firstParagraph, firstText }
+			: null;
+	}
+
+	const rawType = match[1] ?? '';
+	const type = rawType.toUpperCase();
+	const markerSource = match[0];
+	const title = (match[2] ?? '').trim();
+	const firstTextRemainder = firstText.value.slice(markerSource.length);
+	const firstParagraphRemainder = [
+		{ ...firstText, value: firstTextRemainder },
+		...(firstParagraph.children?.slice(1) ?? []),
+	];
+	const hasBody = firstParagraphRemainder.some(hasMeaningfulContent)
+		|| (node.children?.slice(1) ?? []).some(hasMeaningfulContent);
+
+	return {
+		firstParagraph,
+		firstText,
+		firstTextRemainder,
+		hasBody,
+		malformed: false,
+		markerSource,
+		rawType,
+		supported: semanticCalloutTypeSet.has(type),
+		title,
+		type,
+	};
+};
+
+const formatDiagnostic = ({ code, fix, label, line, message, offset }) => ({
+	code,
+	fix,
+	line,
+	message: `${label} line ${line}: ${message}`,
+	offset,
+});
+
+export const getSemanticCalloutDiagnostics = (tree, options = {}) => {
+	const diagnostics = [];
+	const label = options.label ?? 'Markdown';
+	const lineOffset = options.lineOffset ?? 0;
+
+	const visit = (node, blockquoteDepth = 0) => {
+		if (!node || typeof node !== 'object') return;
+		const nextBlockquoteDepth = blockquoteDepth + (node.type === 'blockquote' ? 1 : 0);
+		const marker = getSemanticCalloutMarker(node);
+
+		if (marker) {
+			const line = lineOffset + (node.position?.start.line ?? 1);
+			const offset = node.position?.start.offset ?? 0;
+			let issue = null;
+
+			if (blockquoteDepth > 0) {
+				issue = {
+					code: 'nested-semantic-callout',
+					message: 'Semantic callouts cannot be nested inside another blockquote or callout.',
+					fix: 'Move the inner callout after the surrounding blockquote.',
+				};
+			} else if (marker.malformed) {
+				issue = {
+					code: 'invalid-semantic-callout-marker',
+					message: 'This blockquote starts like a semantic callout but its marker is incomplete.',
+					fix: 'Write the marker on its own first line, for example "> [!WARNING]".',
+				};
+			} else if (marker.rawType !== marker.type) {
+				issue = {
+					code: 'invalid-semantic-callout-type-case',
+					message: `Semantic callout type "${marker.rawType}" must use uppercase ASCII letters.`,
+					fix: `Write "> [!${marker.type}]".`,
+				};
+			} else if (!marker.supported) {
+				issue = {
+					code: 'unknown-semantic-callout-type',
+					message: `Unknown semantic callout type "${marker.rawType}".`,
+					fix: `Use one of: ${semanticCalloutTypes.join(', ')}.`,
+				};
+			} else if (marker.title) {
+				issue = {
+					code: 'unsupported-semantic-callout-title',
+					message: `Semantic callout markers cannot contain a custom title ("${marker.title}").`,
+					fix: `Keep "> [!${marker.type}]" on its own line. Begin the callout body with bold text when local emphasis is useful.`,
+				};
+			} else if (!marker.hasBody) {
+				issue = {
+					code: 'empty-semantic-callout',
+					message: `${marker.type} callout has no content.`,
+					fix: 'Add at least one quoted content line after the marker.',
+				};
+			}
+
+			if (issue) diagnostics.push(formatDiagnostic({ ...issue, label, line, offset }));
+		}
+
+		for (const child of node.children ?? []) visit(child, nextBlockquoteDepth);
+	};
+
+	visit(tree);
+	return diagnostics;
+};

package/scripts/lib/site-content.mjs

@@ -30,6 +30,7 @@ const knownNestedFrontmatterKeys = new Set([
 	'align',
 	'aliases',
 	'alt',
+	'baseUrl',
 	'body',
 	'blockGap',
 	'caption',
@@ -152,7 +153,7 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		} else if (fileKind === 'content' && key === 'description') {
 			fix = 'Indent "description:" under "page:". The optional meta description belongs in the page object.';
 		} else if (fileKind === 'content' && key === 'images') {
-			fix = 'Put local image references in norna-image-stack or norna-image-carousel blocks in the Markdown body.';
+			fix = 'Put local image references in image-stack or image-carousel blocks in the Markdown body.';
 		} else if (fileKind === 'content' && knownThemeTopLevelFrontmatterKeys.has(key)) {
 			fix = `Move "${key}:" to theme.yaml. Visual settings do not belong in content frontmatter.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'navigation') {

package/scripts/lib/site-link-graph.mjs

@@ -2,6 +2,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import {
 	createPageAliasModel,
+	generatedSiteRoutes,
 } from './page-aliases.mjs';
 import { parsePageMarkdownSource } from './page-markdown.mjs';
 import {
@@ -117,6 +118,9 @@ const createPageRecord = ({ contentFile, data = {}, document }) => {
 		anchors,
 		contentFile,
 		document,
+		navigation: {
+			listed: data.navigation?.listed ?? true,
+		},
 		pathname,
 		title: document.pageTitle?.title ?? contentFile.pageId,
 	};
@@ -140,7 +144,13 @@ const looksLikePublicFile = (pathname) => {
 	return (pathname.split('/').at(-1) ?? '').includes('.');
 };
 
-export const createSiteLinkGraph = ({ siteStructure, pageDocuments, publicFiles = [] }) => {
+export const createSiteLinkGraph = ({
+	siteStructure,
+	pageDocuments,
+	publicFiles = [],
+	generatedRoutes,
+}) => {
+	const activeGeneratedRoutes = generatedRoutes ?? generatedSiteRoutes;
 	const documentsByDirectory = new Map(pageDocuments.map(({ contentFile, data, document }) => [
 		contentFile.pageDirectory,
 		{ contentFile, data, document },
@@ -167,7 +177,11 @@ export const createSiteLinkGraph = ({ siteStructure, pageDocuments, publicFiles
 		categories: siteStructure.categories,
 		pages,
 		publicFiles,
+		generatedRoutes: activeGeneratedRoutes,
 	});
+	const generatedRoutesByPathname = new Map(
+		activeGeneratedRoutes.map((route) => [route.pathname, route]),
+	);
 
 	const references = [];
 	const referencesByTarget = new Map();
@@ -249,6 +263,18 @@ export const createSiteLinkGraph = ({ siteStructure, pageDocuments, publicFiles
 				continue;
 			}
 
+			const generatedRoute = generatedRoutesByPathname.get(
+				target.pageLookupPathname ?? target.pathname,
+			);
+			if (generatedRoute && !target.fragment) {
+				reference.resolution = {
+					kind: 'generated-route',
+					pathname: generatedRoute.pathname,
+					route: generatedRoute,
+				};
+				continue;
+			}
+
 			const targetCategory = target.pageLookupPathname
 				? categoriesByPathname.get(target.pageLookupPathname)
 				: null;
@@ -320,7 +346,12 @@ export const getSiteLinkGraph = async (options = {}) => {
 		readPublicFiles(options.publicDir ?? sitePublicDir),
 	]);
 
-	return createSiteLinkGraph({ pageDocuments, publicFiles, siteStructure });
+	return createSiteLinkGraph({
+		pageDocuments,
+		publicFiles,
+		siteStructure,
+		generatedRoutes: options.generatedRoutes,
+	});
 };
 
 export const getSitePublicFiles = async (publicDir = sitePublicDir) => readPublicFiles(publicDir);

package/scripts/lib/site-navigation-tree.mjs

@@ -0,0 +1,85 @@
+export const getSiteNavigationTree = (entries) => {
+	const nodes = new Map();
+	const roots = [];
+
+	for (const entry of entries) {
+		nodes.set(entry.node.pagePath, { ...entry, children: [] });
+	}
+
+	for (const entry of entries) {
+		const node = nodes.get(entry.node.pagePath);
+		if (!node) continue;
+
+		if (entry.node.isHome || entry.node.parentPagePath === null) {
+			roots.push(node);
+			continue;
+		}
+
+		const parent = nodes.get(entry.node.parentPagePath);
+		if (!parent) {
+			throw new Error(`Site node "${entry.node.pagePath}" has no parent node "${entry.node.parentPagePath}".`);
+		}
+
+		parent.children.push(node);
+	}
+
+	return roots;
+};
+
+export const getListedSiteNavigationTree = (entries) => {
+	const filterListed = (nodes) => 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(getSiteNavigationTree(entries));
+};
+
+export const getFirstPageInNavigationNode = (node) => {
+	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) => nodes.flatMap((node) => [
+	node,
+	...flattenSiteNavigationTree(node.children),
+]);
+
+export const getSequentialPageNavigation = (nodes, currentPagePath) => {
+	const activeRoot = nodes.find((root) => (
+		flattenSiteNavigationTree([root]).some(({ node }) => node.pagePath === currentPagePath)
+	));
+	if (!activeRoot) return { previous: null, next: null };
+
+	const pages = flattenSiteNavigationTree([activeRoot])
+		.filter(({ node }) => node.kind === 'page')
+		.map(({ node }) => node);
+	const currentIndex = pages.findIndex(({ pagePath }) => pagePath === currentPagePath);
+	if (currentIndex < 0) return { previous: null, next: null };
+
+	return {
+		previous: pages[currentIndex - 1] ?? null,
+		next: pages[currentIndex + 1] ?? null,
+	};
+};
+
+export const getDirectChildPages = (nodes, currentPagePath) => {
+	const current = flattenSiteNavigationTree(nodes)
+		.find(({ node }) => node.pagePath === currentPagePath);
+	if (!current) return [];
+	const children = current.node.isHome
+		? nodes.filter(({ node }) => !node.isHome)
+		: current.children;
+
+	return children
+		.filter(({ node }) => node.kind === 'page')
+		.map(({ node }) => node);
+};

package/scripts/lib/site-paths.mjs

@@ -5,6 +5,7 @@ import { homePageDirectory } from './site-conventions.mjs';
 
 const siteDirectoryEnvName = 'NORNA_SITE_DIR';
 const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
+const stateDirectoryEnvName = 'NORNA_INTERNAL_STATE_DIR';
 const defaultSiteDirectory = 'site';
 export { homePageDirectory };
 
@@ -16,12 +17,19 @@ export const siteDirectoryEnv = siteDirectoryEnvName;
 
 const normalizeSiteDirectory = (value) => String(value ?? '').trim();
 const normalizeInvocationRoot = (value) => String(value ?? '').trim();
+const normalizeStateDirectory = (value) => String(value ?? '').trim();
 
 const configuredInvocationRoot = normalizeInvocationRoot(process.env[invocationRootEnvName]);
 export const invocationRoot = configuredInvocationRoot
 	? path.resolve(configuredInvocationRoot)
 	: process.cwd();
 
+const hasStateDirectoryEnv = Object.hasOwn(process.env, stateDirectoryEnvName);
+const configuredStateDirectory = normalizeStateDirectory(process.env[stateDirectoryEnvName]);
+if (hasStateDirectoryEnv && !configuredStateDirectory) {
+	throw new Error(`${stateDirectoryEnvName} must not be empty.`);
+}
+
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
 		existsSync(path.join(siteDir, 'config.yaml'))
@@ -126,9 +134,13 @@ export const siteHomePageDir = path.join(sitePagesDir, homePageDirectory);
 export const siteContentPath = path.join(siteHomePageDir, 'content.md');
 export const siteImagesDir = path.join(siteHomePageDir, 'images');
 export const sitePublicDir = path.join(siteDir, 'public');
-export const siteStateDir = path.join(siteDir, '.norna');
+export const siteStateDir = configuredStateDirectory
+	? path.resolve(configuredStateDirectory)
+	: path.join(siteDir, '.norna');
 export const astroPublicDir = path.join(siteStateDir, 'public');
-export const astroDistDir = path.join(siteProjectRoot, 'dist');
+export const astroDistDir = configuredStateDirectory
+	? path.join(siteStateDir, 'dist')
+	: path.join(siteProjectRoot, 'dist');
 export const astroRootDir = siteStateDir;
 export const astroCacheDir = path.join(astroRootDir, '.astro');
 export const generatedImagesDir = path.join(astroPublicDir, 'images', 'generated');

package/scripts/lib/social-image-assets.mjs

@@ -0,0 +1,30 @@
+import { getPublicAssetInspection } from './logo-assets.mjs';
+import {
+	socialImageAssetDefinitions,
+	socialImageAssetFilenames,
+} from './public-asset-conventions.mjs';
+import { sitePublicLabel } from './site-paths.mjs';
+
+const definitionsByFilename = new Map(
+	socialImageAssetDefinitions.map((definition) => [definition.filename, definition]),
+);
+
+export const getSocialImageAssets = () => getPublicAssetInspection().socialImages
+	.map((filename) => ({
+		...definitionsByFilename.get(filename),
+		filename,
+		href: `/${filename}`,
+	}));
+
+export const getSocialImageAsset = () => {
+	const assets = getSocialImageAssets();
+
+	if (assets.length > 1) {
+		throw new Error([
+			`Found multiple social sharing images in ${sitePublicLabel}. Keep exactly one of ${socialImageAssetFilenames.join(', ')}.`,
+			...assets.map(({ filename }) => `- ${sitePublicLabel}/${filename}`),
+		].join('\n'));
+	}
+
+	return assets[0] ?? null;
+};

package/scripts/lib/table-render-plugin.mjs

@@ -0,0 +1,33 @@
+import { defineHastPlugin } from 'satteri';
+
+export const nornaTableRenderPlugin = defineHastPlugin({
+	name: 'norna-table-render',
+	element: {
+		filter: ['table'],
+		visit(node, context) {
+			context.replaceNode(node, {
+				type: 'element',
+				tagName: 'div',
+				properties: {
+					className: ['norna-table-frame', 'content-block-note-lane-boundary'],
+					'data-table-frame': '',
+				},
+				children: [{
+					type: 'element',
+					tagName: 'div',
+					properties: {
+						className: ['norna-table-scroll'],
+						'data-table-scroll': '',
+						tabIndex: 0,
+					},
+					children: [{
+						type: 'element',
+						tagName: node.tagName,
+						properties: { ...(node.properties ?? {}) },
+						children: [...(node.children ?? [])],
+					}],
+				}],
+			});
+		},
+	},
+});

package/scripts/lib/theme-presets.mjs

@@ -4,7 +4,7 @@ import { resolveThemeProfileRecipe } from './theme-profiles.mjs';
 
 export const themePresetRecipes = Object.freeze({
 	portfolio: Object.freeze({
-		color: 'near-monochrome-dark',
+		color: 'near-monochrome-adaptive',
 		typography: 'restrained-sans',
 		rhythm: 'balanced',
 		geometry: 'image-led',
@@ -231,7 +231,7 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'blocks:',
 		'  cardList:',
 		'    # Alternatives: text, narrow, normal, wide.',
-		'    # A width written in a norna-card-list block overrides this default.',
+		'    # A width written in a card-list block overrides this default.',
 		`    width: ${blocks.cardList.width}`,
 		'',
 		'typography:',

package/scripts/lib/theme-profiles.mjs

@@ -2,10 +2,6 @@ import { freezeDeep, mergeDeep } from './object.mjs';
 
 export const themeProfileDefinitions = freezeDeep({
 	color: {
-		'near-monochrome-dark': {
-			appearance: { default: 'dark' },
-			palette: 'near-monochrome',
-		},
 		'near-monochrome-adaptive': {
 			appearance: { default: 'system' },
 			palette: 'near-monochrome',