@janga/norna 0.7.18 → 0.7.23

package/scripts/lib/schema-value-definitions.mjs

@@ -2,6 +2,10 @@ import {
 	getThemePresetMetadata,
 	themePresetNames,
 } from './theme-presets.mjs';
+import {
+	getPresentationPaletteMetadata,
+	presentationPaletteNames,
+} from './presentation-palette-metadata.mjs';
 
 const option = (title, description) => Object.freeze({ title, description });
 const definition = (values, options) => Object.freeze({
@@ -19,10 +23,10 @@ export const schemaValueDefinitions = Object.freeze([
 		smooth: option('Browser smooth', 'Use the browser\'s native smooth scrolling for anchor navigation.'),
 	}),
 	definition(['automatic', 'sections', 'top', 'tree'], {
-		automatic: option('Automatic', 'Choose sections for one page, top navigation for a shallow multi-page site, and tree navigation for deeper content.'),
+		automatic: option('Automatic', 'Choose sections for one page, top navigation for Home and independent top-level pages, and tree navigation inside branches with listed children or categories.'),
 		sections: option('Sections', 'Navigate the sections of the current page.'),
 		top: option('Top', 'Use pages in the top navigation and sections below them.'),
-		tree: option('Tree', 'Use a hierarchical site-wide navigation tree.'),
+		tree: option('Tree', 'Use a left page rail and a separate right H2/H3 contents rail where the page has enough headings.'),
 	}),
 	definition(['en', 'sv'], {
 		en: option('English', 'Use Norna\'s built-in English interface text.'),
@@ -44,6 +48,16 @@ export const schemaValueDefinitions = Object.freeze([
 		normal: option('Normal', 'Use the balanced default line length.'),
 		wide: option('Wide', 'Allow body text to use more horizontal space.'),
 	}),
+	definition(['text', 'narrow', 'normal', 'wide'], {
+		text: option('Text width', 'Match the active body-text width, including a reader-selected reading width.'),
+		narrow: option('Narrow', 'Limit the complete card list to at most 48rem.'),
+		normal: option('Normal', 'Limit the complete card list to at most 56rem.'),
+		wide: option('Wide', 'Allow the complete card list to use the available page-layout width.'),
+	}),
+	definition(['prose-aligned', 'centered-fit'], {
+		'prose-aligned': option('Prose-aligned', 'Start managed images and captions at the body-text edge and size them from the page content area.'),
+		'centered-fit': option('Centered fit', 'Center managed images and captions in the page media area and constrain them by available width and viewport height.'),
+	}),
 	definition([400, 500, 600, 700], {
 		400: option('Regular', 'Use regular font weight.'),
 		500: option('Medium', 'Use medium font weight.'),
@@ -56,19 +70,23 @@ export const schemaValueDefinitions = Object.freeze([
 		reading: option('Reading', 'Reading-focused typography with narrower text and relaxed line height.'),
 		statement: option('Statement', 'Stronger headings and tighter body rhythm for short, expressive pages.'),
 	}),
-	definition(['dark', 'light', 'paper'], {
-		dark: option('Dark', 'Black page and section surfaces with light text.'),
-		light: option('Light', 'White and cool light surfaces with dark text.'),
-		paper: option('Paper', 'Warm off-white surfaces with dark text.'),
+	definition(presentationPaletteNames, Object.fromEntries(presentationPaletteNames.map((name) => {
+		const metadata = getPresentationPaletteMetadata(name);
+		return [name, option(metadata.title, `${metadata.description} Includes coordinated light and dark variants.`)];
+	}))),
+	definition(['system', 'light', 'dark'], {
+		system: option('System', 'Follow the visitor\'s operating-system light or dark preference.'),
+		light: option('Light', 'Start with the palette\'s light appearance.'),
+		dark: option('Dark', 'Start with the palette\'s dark appearance.'),
 	}),
-	definition(['square', 'soft'], {
+	definition(['square', 'rounded'], {
 		square: option('Square', 'Use square corners for navigation, cards and framed content.'),
-		soft: option('Soft', 'Use restrained rounded corners consistently across the site.'),
+		rounded: option('Rounded', 'Use restrained rounded corners consistently across the site.'),
 	}),
-	definition(['uniform', 'alternating', 'cycling'], {
-		uniform: option('Uniform', 'Use the palette base surface for every section.'),
-		alternating: option('Alternating', 'Alternate between the palette base and soft surfaces.'),
-		cycling: option('Cycling', 'Cycle through the palette base, soft and emphasis surfaces.'),
+	definition(['uniform', 'alternating', 'accented'], {
+		uniform: option('Uniform', 'Use the normal page background for every H2 section. Tree navigation requires this pattern.'),
+		alternating: option('Alternating', 'Alternate normal and subtly contrasting full-width section backgrounds. Available with sections and top navigation.'),
+		accented: option('Accented', 'Move through base, soft, emphasis and soft full-width section backgrounds before repeating. Available with sections and top navigation.'),
 	}),
 	definition(['compact', 'normal', 'spacious'], {
 		compact: option('Compact', 'Use restrained spacing between sections and structured blocks.'),

package/scripts/lib/site-content.mjs

@@ -1,18 +1,17 @@
-import { access, readdir, readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
+import {
+	schemaTopLevelKeys,
+	siteSchema,
+} from './schema-definitions.mjs';
 import {
 	siteContentLabel,
-	siteDir,
-	siteDirLabel,
-	homePageDirectory,
-	siteImagesLabel,
-	sitePagesDir,
-	sitePagesLabel,
 	sitewideContentLabel,
 } from './site-paths.mjs';
-import { parsePageDirectoryPath } from './page-model.mjs';
-import { getMarkdownHeadings } from './heading-ids.mjs';
-import { schemaTopLevelKeys } from './schema-definitions.mjs';
+import { getIndentInfo, validateYamlIndentation } from './yaml-indentation.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+
+export { getContentFiles } from './site-structure.mjs';
 
 export const rasterImageExtensions = new Set(['.jpg', '.jpeg', '.png']);
 export const staticImageExtensions = new Set(['.svg']);
@@ -29,13 +28,16 @@ const knownPageThemeTopLevelFrontmatterKeys = new Set(
 const knownSitewideTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.sitewide);
 const knownNestedFrontmatterKeys = new Set([
 	'align',
+	'aliases',
 	'alt',
 	'body',
 	'blockGap',
 	'caption',
+	'appearance',
 	'carousel',
 	'contentSpacing',
 	'desktop',
+	'default',
 	'fontFamily',
 	'from',
 	'finalSectionBottom',
@@ -64,11 +66,14 @@ const knownNestedFrontmatterKeys = new Set([
 	'palette',
 	'preset',
 	'profile',
+	'readerControls',
+	'readingWidth',
 	'rhythm',
 	'sectionGap',
 	'backgroundPattern',
 	'sections',
-	'shape',
+	'corners',
+	'focusReading',
 	'size',
 	'spacingAfter',
 	'spacingBefore',
@@ -82,107 +87,6 @@ const knownNestedFrontmatterKeys = new Set([
 
 export const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
 
-const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
-
-export const getContentFiles = async () => {
-	const legacyContentPath = path.join(siteDir, 'content.md');
-	const legacyImagesPath = path.join(siteDir, 'images');
-	const legacyPaths = [];
-	if (await fileExists(legacyContentPath)) legacyPaths.push(`${siteDirLabel}/content.md`);
-	if (await fileExists(legacyImagesPath)) legacyPaths.push(`${siteDirLabel}/images`);
-	if (legacyPaths.length > 0) {
-		throw new Error([
-			`The old root-page structure is no longer supported: ${legacyPaths.join(', ')}.`,
-			`Move the homepage content to ${sitePagesLabel}/${homePageDirectory}/content.md and its images to ${sitePagesLabel}/${homePageDirectory}/images/.`,
-		].join('\n'));
-	}
-
-	const legacyRoutesDir = path.join(siteDir, 'routes');
-	const legacyRoutes = await readdir(legacyRoutesDir).catch((error) => {
-		if (error?.code === 'ENOENT') return null;
-		throw error;
-	});
-	if (legacyRoutes !== null) {
-		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
-	}
-
-	const contentFiles = [];
-	const collectPageContentFiles = async (pagesDir, pagesLabel, parentPageDirectory = '') => {
-		const pageEntries = await readdir(pagesDir, { withFileTypes: true }).catch((error) => {
-		if (error?.code === 'ENOENT') {
-			return [];
-		}
-
-		throw error;
-		});
-
-		for (const entry of pageEntries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
-			if (!entry.isDirectory()) continue;
-
-			const pageDirectory = parentPageDirectory
-				? `${parentPageDirectory}/pages/${entry.name}`
-				: entry.name;
-			const pageLabel = `${pagesLabel}/${entry.name}`;
-			const pageDir = path.join(pagesDir, entry.name);
-			const pageContentPath = path.join(pageDir, 'content.md');
-
-			if (!(await fileExists(pageContentPath))) {
-				const childPageEntries = await readdir(path.join(pageDir, 'pages'), { withFileTypes: true }).catch((error) => {
-					if (error?.code === 'ENOENT') return [];
-					throw error;
-				});
-				if (childPageEntries.some((childEntry) => childEntry.isDirectory())) {
-					throw new Error(`${pageLabel} contains nested pages but has no content.md of its own.`);
-				}
-				continue;
-			}
-			const pageMetadata = parsePageDirectoryPath(pageDirectory, pageLabel);
-			const isHome = pageDirectory === homePageDirectory;
-
-			contentFiles.push({
-				contentLabel: `${pageLabel}/content.md`,
-				contentPath: pageContentPath,
-				imagesDir: path.join(pageDir, 'images'),
-				imagesLabel: `${pageLabel}/images`,
-				isHome,
-				...pageMetadata,
-				pagePath: isHome ? '' : pageMetadata.pagePath,
-				parentPagePath: isHome ? null : pageMetadata.parentPagePath,
-			});
-
-			if (isHome) {
-				const homePagesDir = path.join(pageDir, 'pages');
-				const homeChildEntries = await readdir(homePagesDir, { withFileTypes: true }).catch((error) => {
-					if (error?.code === 'ENOENT') return [];
-					throw error;
-				});
-				const homeChildDirectories = homeChildEntries.filter((childEntry) => childEntry.isDirectory());
-				if (homeChildDirectories.length > 0) {
-					throw new Error([
-						`${pageLabel} is the homepage and cannot contain child pages.`,
-						`Move these page directories beside ${homePageDirectory} under ${sitePagesLabel}/, or below another non-home page:`,
-						...homeChildDirectories.map(({ name }) => `- ${pageLabel}/pages/${name}`),
-					].join('\n'));
-				}
-				continue;
-			}
-
-			await collectPageContentFiles(
-				path.join(pageDir, 'pages'),
-				`${pageLabel}/pages`,
-				pageDirectory,
-			);
-		}
-	};
-
-	await collectPageContentFiles(sitePagesDir, sitePagesLabel);
-	if (!contentFiles.some(({ isHome }) => isHome)) {
-		throw new Error(`Homepage content is missing. Create ${siteContentLabel}.`);
-	}
-
-	return contentFiles;
-};
-
 export const splitSiteFile = (source, label = siteContentLabel) => {
 	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
 
@@ -205,91 +109,17 @@ export const splitSiteFile = (source, label = siteContentLabel) => {
 	};
 };
 
-export const readSiteFile = async (sitePath, label = siteContentLabel) => splitSiteFile(await readFile(sitePath, 'utf8'), label);
-
-const getIndentInfo = (line) => {
-	const characters = Array.from(line);
-	const indentCharacters = [];
-
-	for (const character of characters) {
-		if (character === ' ' || character === '\t' || character === '\u00a0' || character === '\uFFFD' || character === '\u00c2') {
-			indentCharacters.push(character);
-			continue;
-		}
-
-		break;
-	}
-
-	return {
-		indent: indentCharacters.length,
-		hasInvalidWhitespace: indentCharacters.some((character) => character !== ' '),
-	};
-};
-
-const getNextFrontmatterEntry = (lines, startIndex) => {
-	for (let index = startIndex + 1; index < lines.length; index += 1) {
-		const line = lines[index];
-		if (!line.trim() || line.trim().startsWith('#') || frontmatterDelimiterRegex.test(line)) {
-			continue;
-		}
-
-		return {
-			index,
-			line,
-			...getIndentInfo(line),
-		};
-	}
-
-	return null;
+export const readSiteFile = async (sitePath, label = siteContentLabel) => {
+	const source = await readFile(sitePath, 'utf8');
+	return { ...splitSiteFile(source, label), source };
 };
 
 export const validateFrontmatterIndentation = (frontmatter, addIssue) => {
-	const lines = frontmatter.split(/\r?\n/);
-
-	for (const [index, line] of lines.entries()) {
-		const lineNumber = index + 1;
-		const trimmed = line.trim();
-
-		if (!trimmed || trimmed.startsWith('#') || frontmatterDelimiterRegex.test(line)) {
-			continue;
-		}
-
-		const { indent, hasInvalidWhitespace } = getIndentInfo(line);
-
-		if (hasInvalidWhitespace) {
-			addIssue({
-				severity: 'error',
-				message: `Frontmatter line ${lineNumber} uses tabs, non-breaking spaces, or invalid whitespace for indentation.`,
-				fix: 'Replace the indentation on that line with ordinary spaces.',
-			});
-			continue;
-		}
-
-		if (indent % 2 !== 0) {
-			addIssue({
-				severity: 'error',
-				message: `Frontmatter line ${lineNumber} is indented with ${indent} spaces.`,
-				fix: 'Use 2-space indentation levels in frontmatter.',
-			});
-		}
-
-		const keyValueMatch = line.match(/^(\s*)[A-Za-z][A-Za-z0-9-]*:\s+(.+)$/);
-		if (!keyValueMatch) continue;
-
-		const value = keyValueMatch[2].trim();
-		if (value === '|' || value === '>' || value.startsWith('|') || value.startsWith('>')) {
-			continue;
-		}
-
-		const nextEntry = getNextFrontmatterEntry(lines, index);
-		if (!nextEntry || nextEntry.indent <= indent) continue;
-
-		addIssue({
-			severity: 'error',
-			message: `Frontmatter line ${nextEntry.index + 1} is indented under line ${lineNumber}, but line ${lineNumber} already has a value.`,
-			fix: 'Move the later line to the same indentation level as its sibling, or place it under a key that has no value.',
-		});
-	}
+	validateYamlIndentation(frontmatter, (issue) => addIssue({
+		...issue,
+		message: issue.message.replace(/^YAML/, 'Frontmatter'),
+		fix: issue.fix.replace(/YAML/g, 'frontmatter'),
+	}));
 };
 
 export const validateFrontmatterStructure = (frontmatter, addIssue, {
@@ -328,7 +158,19 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'navigation') {
 			message = `Frontmatter line ${lineNumber}: navigation is technical, site-wide configuration and does not belong in ${fileKind}. Set it in config.yaml.`;
 			fix = 'Set the navigation mode under "navigation:" in config.yaml.';
-		} else if (fileKind === 'page theme' && ['preset', 'shape', 'palette', 'typography'].includes(key)) {
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'shape') {
+			message = fileKind === 'page theme'
+				? `Frontmatter line ${lineNumber}: "shape" was replaced by the site-wide "corners" setting, which page themes cannot override.`
+				: `Frontmatter line ${lineNumber}: "shape" was replaced by "corners". Use "square" or replace the old "soft" value with "rounded".`;
+			fix = fileKind === 'page theme'
+				? 'Remove "shape:" from this page theme. Set "corners: square" or "corners: rounded" in the root theme.yaml when an override is needed.'
+				: 'Replace "shape:" with "corners:". Use "square" or replace the old "soft" value with "rounded".';
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'colorMode') {
+			message = `Frontmatter line ${lineNumber}: Theme setting "colorMode" was replaced by "appearance".`;
+			fix = fileKind === 'page theme'
+				? 'Remove "colorMode:" from this page theme. Set "appearance:" in the root theme.yaml when an override is needed.'
+				: 'Replace "colorMode:" with "appearance:".';
+		} else if (fileKind === 'page theme' && ['preset', 'appearance', 'readerControls', 'corners', 'palette', 'typography'].includes(key)) {
 			message = `Frontmatter line ${lineNumber}: page themes may not define site-wide visual identity through "${key}".`;
 			fix = `Move "${key}:" to the root theme.yaml. Page themes may set only layout.textWidth, layout.contentSpacing, images, and sections.backgroundPattern.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && ['logo', 'site'].includes(key)) {
@@ -357,6 +199,15 @@ export const validateContentFrontmatterStructure = (frontmatter, addIssue) =>
 		fileKind: 'content',
 	});
 
+export const parseContentFrontmatter = (frontmatterBody, label = siteContentLabel) => parseYamlConfig(
+	frontmatterBody,
+	`${label} frontmatter`,
+	{
+		schema: siteSchema,
+		validateStructure: validateContentFrontmatterStructure,
+	},
+);
+
 export const validateConfigYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownConfigTopLevelFrontmatterKeys,
@@ -389,31 +240,6 @@ export const readThemeFile = async (sitePath) => {
 export const getDeprecatedInlineStyleReferences = (body) => Array.from(body.matchAll(deprecatedInlineStyleReferenceRegex))
 	.map((match) => match[1]);
 
-export const getBodySections = async (body) => {
-	const { headings, source } = await getMarkdownHeadings(body);
-	const structuralHeadings = headings.filter((heading) => heading.depth <= 2);
-	const prelude = structuralHeadings.length > 0 ? source.slice(0, structuralHeadings[0].index) : source;
-	const sections = structuralHeadings.map((heading, index) => {
-		const next = structuralHeadings[index + 1];
-		const end = next?.index ?? source.length;
-
-		return {
-			...heading,
-			heading: heading.source,
-			isPageTitle: heading.depth === 1,
-			level: heading.depth,
-			text: source.slice(heading.index, end).trimEnd(),
-		};
-	});
-
-	return {
-		headings,
-		pageHeadings: sections.filter((section) => section.isPageTitle),
-		prelude,
-		sections,
-	};
-};
-
 export const getImageFiles = async (directory) => {
 	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
 		if (error?.code === 'ENOENT') {
@@ -437,25 +263,6 @@ export const getImageFiles = async (directory) => {
 	return files;
 };
 
-export const getImageIndex = async (contentDir, fail, contentLabel = siteImagesLabel) => {
-	const imageFiles = await getImageFiles(contentDir);
-	const imagesByName = new Map();
-
-	for (const imagePath of imageFiles) {
-		const imageName = path.basename(imagePath);
-		const existingPath = imagesByName.get(imageName);
-
-		if (existingPath) {
-			fail(`Duplicate image filename "${imageName}" found at ${contentLabel}/${toPosixPath(path.relative(contentDir, existingPath))} and ${contentLabel}/${toPosixPath(path.relative(contentDir, imagePath))}. The filename is ambiguous within this page image root.`);
-			continue;
-		}
-
-		imagesByName.set(imageName, imagePath);
-	}
-
-	return imagesByName;
-};
-
 export const getImageCandidatesByName = async (contentDir) => {
 	const imageFiles = await getImageFiles(contentDir);
 	const imagesByName = new Map();