@janga/norna 0.7.17 → 0.7.22

package/scripts/lib/site-conventions.mjs

@@ -0,0 +1 @@
+export const homePageDirectory = '000-home';

package/scripts/lib/site-paths.mjs

@@ -1,10 +1,12 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { homePageDirectory } from './site-conventions.mjs';
 
 const siteDirectoryEnvName = 'NORNA_SITE_DIR';
 const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
 const defaultSiteDirectory = 'site';
+export { homePageDirectory };
 
 const currentFile = fileURLToPath(import.meta.url);
 const currentDirectory = path.dirname(currentFile);
@@ -23,7 +25,10 @@ export const invocationRoot = configuredInvocationRoot
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
 		existsSync(path.join(siteDir, 'config.yaml'))
-		&& existsSync(path.join(siteDir, 'content.md'))
+		&& (
+			existsSync(path.join(siteDir, 'pages', homePageDirectory, 'content.md'))
+			|| existsSync(path.join(siteDir, 'content.md'))
+		)
 	);
 };
 
@@ -95,7 +100,6 @@ const resolveSitePaths = () => {
 const resolvedSitePaths = resolveSitePaths();
 
 export const siteProjectRoot = resolvedSitePaths.siteProjectRoot;
-export const root = siteProjectRoot;
 export const siteDirectory = resolvedSitePaths.siteDirectory;
 
 if (!siteDirectory) {
@@ -116,21 +120,22 @@ const getPathLabel = (filePath) => {
 export const siteDir = resolvedSitePaths.siteDir;
 export const siteConfigPath = path.join(siteDir, 'config.yaml');
 export const siteThemePath = path.join(siteDir, 'theme.yaml');
-export const siteContentPath = path.join(siteDir, 'content.md');
 export const sitewideContentPath = path.join(siteDir, 'sitewide-content.yaml');
-export const siteImagesDir = path.join(siteDir, 'images');
 export const sitePagesDir = path.join(siteDir, 'pages');
+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 astroPublicDir = path.join(siteStateDir, 'public');
 export const astroDistDir = path.join(siteProjectRoot, 'dist');
-export const astroCacheDir = path.join(siteProjectRoot, '.astro');
+export const astroRootDir = siteStateDir;
+export const astroCacheDir = path.join(astroRootDir, '.astro');
 export const generatedImagesDir = path.join(astroPublicDir, 'images', 'generated');
 export const originalImagesDir = path.join(astroPublicDir, 'images', 'original');
 export const generatedImagesManifestPath = path.join(siteStateDir, 'generated-images.json');
 
 export const engineRootLabel = getPathLabel(engineRoot);
-export const invocationRootLabel = getPathLabel(invocationRoot);
 export const siteProjectRootLabel = getPathLabel(siteProjectRoot);
 export const siteDirLabel = getPathLabel(siteDir);
 export const siteConfigLabel = getPathLabel(siteConfigPath);

package/scripts/lib/site-structure.mjs

@@ -0,0 +1,189 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { categorySchema } from './schema-definitions.mjs';
+import { parsePageDirectoryPath } from './page-model.mjs';
+import {
+	homePageDirectory,
+	siteContentLabel,
+	siteDir,
+	siteDirLabel,
+	sitePagesDir,
+	sitePagesLabel,
+} from './site-paths.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+
+const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
+
+const readDirectory = async (directory) => readdir(directory, { withFileTypes: true }).catch((error) => {
+	if (error?.code === 'ENOENT') return [];
+	throw error;
+});
+
+const compareNodeMetadata = (left, right) => (
+	left.pageOrder - right.pageOrder
+	|| left.pageId.localeCompare(right.pageId, 'en')
+);
+
+const assertLegacyStructureIsAbsent = 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'));
+	}
+
+	if (await fileExists(path.join(siteDir, 'routes'))) {
+		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
+	}
+};
+
+const assertUniqueSiblings = (nodes, pagesLabel) => {
+	const byId = new Map();
+	const byOrder = new Map();
+
+	for (const node of nodes) {
+		const existingId = byId.get(node.pageId);
+		if (existingId) {
+			throw new Error([
+				`${pagesLabel} contains duplicate sibling id "${node.pageId}".`,
+				`- ${existingId.nodeLabel}`,
+				`- ${node.nodeLabel}`,
+			].join('\n'));
+		}
+		byId.set(node.pageId, node);
+
+		const existingOrder = byOrder.get(node.pageOrder);
+		if (existingOrder) {
+			throw new Error([
+				`${pagesLabel} contains duplicate sibling order "${String(node.pageOrder).padStart(3, '0')}".`,
+				`- ${existingOrder.nodeLabel}`,
+				`- ${node.nodeLabel}`,
+			].join('\n'));
+		}
+		byOrder.set(node.pageOrder, node);
+	}
+};
+
+const readCategory = async (categoryPath, categorySourceLabel) => {
+	const source = await readFile(categoryPath, 'utf8');
+	return parseYamlConfig(source, categorySourceLabel, { schema: categorySchema });
+};
+
+export const getSiteStructure = async () => {
+	await assertLegacyStructureIsAbsent();
+
+	const nodes = [];
+	const warnings = [];
+
+	const collectNodes = async (pagesDir, pagesLabel, parentNodeDirectory = '') => {
+		const entries = (await readDirectory(pagesDir))
+			.filter((entry) => entry.isDirectory())
+			.sort((left, right) => left.name.localeCompare(right.name, 'en'));
+		const siblingNodes = [];
+
+		for (const entry of entries) {
+			const pageDirectory = parentNodeDirectory
+				? `${parentNodeDirectory}/pages/${entry.name}`
+				: entry.name;
+			const nodeLabel = `${pagesLabel}/${entry.name}`;
+			const nodeDir = path.join(pagesDir, entry.name);
+			const contentPath = path.join(nodeDir, 'content.md');
+			const categoryPath = path.join(nodeDir, 'category.yaml');
+			const [hasContent, hasCategory] = await Promise.all([
+				fileExists(contentPath),
+				fileExists(categoryPath),
+			]);
+			const metadata = parsePageDirectoryPath(pageDirectory, nodeLabel);
+
+			if (hasContent === hasCategory) {
+				const problem = hasContent
+					? 'contains both content.md and category.yaml'
+					: 'contains neither content.md nor category.yaml';
+				throw new Error(`${nodeLabel} ${problem}. Keep exactly one: content.md for a page, or category.yaml for a navigation category.`);
+			}
+
+			const isHome = pageDirectory === homePageDirectory;
+			if (isHome && hasCategory) {
+				throw new Error(`${nodeLabel}/category.yaml is invalid. The homepage must be a page with content.md.`);
+			}
+
+			const node = {
+				...metadata,
+				isHome,
+				kind: hasCategory ? 'category' : 'page',
+				nodeDir,
+				nodeLabel,
+				pagePath: isHome ? '' : metadata.pagePath,
+				parentPagePath: isHome ? null : metadata.parentPagePath,
+			};
+
+			if (hasCategory) {
+				if (await fileExists(path.join(nodeDir, 'images'))) {
+					throw new Error(`${nodeLabel} is a navigation category and cannot contain images/. Use content.md when the collection needs editorial content or images.`);
+				}
+				const category = await readCategory(categoryPath, `${nodeLabel}/category.yaml`);
+				Object.assign(node, {
+					categorySourceLabel: `${nodeLabel}/category.yaml`,
+					categoryPath,
+					label: category.label,
+				});
+			} else {
+				Object.assign(node, {
+					contentLabel: `${nodeLabel}/content.md`,
+					contentPath,
+					imagesDir: path.join(nodeDir, 'images'),
+					imagesLabel: `${nodeLabel}/images`,
+				});
+			}
+
+			siblingNodes.push(node);
+		}
+
+		assertUniqueSiblings(siblingNodes, pagesLabel);
+
+		for (const node of siblingNodes.sort(compareNodeMetadata)) {
+			nodes.push(node);
+			const childPagesDir = path.join(node.nodeDir, 'pages');
+			const childDirectories = (await readDirectory(childPagesDir)).filter((entry) => entry.isDirectory());
+
+			if (node.isHome && childDirectories.length > 0) {
+				throw new Error([
+					`${node.nodeLabel} is the homepage and cannot contain child pages.`,
+					`Move these page directories beside ${homePageDirectory} under ${sitePagesLabel}/, or below another non-home page:`,
+					...childDirectories.map(({ name }) => `- ${node.nodeLabel}/pages/${name}`),
+				].join('\n'));
+			}
+
+			if (node.kind === 'category' && childDirectories.length === 0) {
+				warnings.push({
+					code: 'empty-category',
+					label: node.categorySourceLabel,
+					message: `${node.categorySourceLabel} defines an empty navigation category. Add at least one child page under ${node.nodeLabel}/pages/.`,
+				});
+			}
+
+			if (!node.isHome && childDirectories.length > 0) {
+				await collectNodes(childPagesDir, `${node.nodeLabel}/pages`, node.pageDirectory);
+			}
+		}
+	};
+
+	await collectNodes(sitePagesDir, sitePagesLabel);
+	if (!nodes.some(({ isHome }) => isHome)) {
+		throw new Error(`Homepage content is missing. Create ${siteContentLabel}.`);
+	}
+
+	return {
+		categories: nodes.filter(({ kind }) => kind === 'category'),
+		contentFiles: nodes.filter(({ kind }) => kind === 'page'),
+		nodes,
+		warnings,
+	};
+};
+
+export const getContentFiles = async () => (await getSiteStructure()).contentFiles;

package/scripts/lib/theme-config.mjs

@@ -12,6 +12,7 @@ import {
 } from './site-paths.mjs';
 import { resolveThemePresentation } from './presentation.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
+import { pageThemeSchema, themeVisualSchema } from './schema-definitions.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
 
 export const readThemeConfig = async () => {
@@ -23,6 +24,7 @@ export const readThemeConfig = async () => {
 		throw error;
 	});
 	const config = parseYamlConfig(themeFile, siteThemeLabel, {
+		schema: themeVisualSchema,
 		validateStructure: validateThemeYamlStructure,
 	});
 	resolveThemeConfig(config, siteThemeLabel);
@@ -64,10 +66,9 @@ export const validatePageThemeFiles = async () => {
 	for (const file of files) {
 		const source = await readFile(file.path, 'utf8');
 		const config = parseYamlConfig(source, file.label, {
+			schema: pageThemeSchema,
 			validateStructure: validatePageThemeYamlStructure,
 		});
-		resolveThemeConfig(config, file.label);
-		resolveThemePresentation(config, file.label);
 
 		configs.push({ ...file, config });
 	}

package/scripts/lib/theme-presets.mjs

@@ -1,97 +1,47 @@
-import { mergeDeep } from './typography.mjs';
+import { freezeDeep, mergeDeep } from './object.mjs';
+import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
+import { resolveThemeProfileRecipe } from './theme-profiles.mjs';
 
-const themePresetConfigurations = Object.freeze({
+export const themePresetRecipes = Object.freeze({
 	portfolio: Object.freeze({
-		navigation: { mode: 'automatic' },
-		layout: {
-			density: 'normal',
-			pageWidth: '1240px',
-			gutter: {
-				desktop: 'clamp(1.25rem, 4vw, 3rem)',
-				mobile: '1rem',
-			},
-		},
-		images: {
-			width: '1000px',
-			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
-			maxAvailableHeightPercent: { desktop: 78, mobile: 68 },
-		},
-		typography: {
-			fontFamily: "'Helvetica Neue', Arial, sans-serif",
-			profile: 'restrained',
-			rhythm: 'normal',
-		},
-		palette: 'dark',
-		sectionSurfaces: ['base'],
+		color: 'near-monochrome-dark',
+		typography: 'restrained-sans',
+		rhythm: 'balanced',
+		geometry: 'image-led',
+		media: 'prominent',
+		blocks: 'wide-cards',
+		corners: 'square',
+		surfaces: 'uniform',
 	}),
 	documentation: Object.freeze({
-		navigation: { mode: 'automatic' },
-		layout: {
-			density: 'compact',
-			pageWidth: '1240px',
-			gutter: {
-				desktop: 'clamp(1.25rem, 4vw, 3rem)',
-				mobile: '1rem',
-			},
-		},
-		images: {
-			width: '920px',
-			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
-			maxAvailableHeightPercent: { desktop: 74, mobile: 68 },
-		},
-		typography: {
-			fontFamily: "Georgia, 'Times New Roman', serif",
-			profile: 'reading',
-			rhythm: 'compact',
-		},
-		palette: 'paper',
-		sectionSurfaces: ['base', 'soft'],
+		color: 'warm-paper-adaptive',
+		typography: 'editorial-reading',
+		rhythm: 'compact',
+		geometry: 'focused-reading',
+		media: 'supporting',
+		blocks: 'reading-column-cards',
+		corners: 'rounded',
+		surfaces: 'alternating',
 	}),
 	project: Object.freeze({
-		navigation: { mode: 'automatic' },
-		layout: {
-			density: 'compact',
-			pageWidth: '1120px',
-			gutter: {
-				desktop: 'clamp(1.25rem, 4vw, 3rem)',
-				mobile: '1rem',
-			},
-		},
-		images: {
-			width: '840px',
-			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
-			maxAvailableHeightPercent: { desktop: 70, mobile: 62 },
-		},
-		typography: {
-			fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
-			profile: 'reading',
-			rhythm: 'compact',
-		},
-		palette: 'light',
-		sectionSurfaces: ['base', 'soft'],
+		color: 'near-monochrome-adaptive',
+		typography: 'system-reading',
+		rhythm: 'compact',
+		geometry: 'balanced-site',
+		media: 'balanced',
+		blocks: 'balanced-cards',
+		corners: 'rounded',
+		surfaces: 'alternating',
 	}),
 	statement: Object.freeze({
-		navigation: { mode: 'automatic' },
-		layout: {
-			density: 'airy',
-			pageWidth: '1280px',
-			gutter: {
-				desktop: 'clamp(1.5rem, 5vw, 4rem)',
-				mobile: '1rem',
-			},
-		},
-		images: {
-			width: '1080px',
-			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
-			maxAvailableHeightPercent: { desktop: 80, mobile: 70 },
-		},
-		typography: {
-			fontFamily: "'Trebuchet MS', 'Helvetica Neue', Arial, sans-serif",
-			profile: 'statement',
-			rhythm: 'airy',
-		},
-		palette: 'paper',
-		sectionSurfaces: ['base', 'emphasis'],
+		color: 'warm-paper-adaptive',
+		typography: 'expressive-sans',
+		rhythm: 'expansive',
+		geometry: 'expansive-statement',
+		media: 'immersive',
+		blocks: 'wide-cards',
+		corners: 'square',
+		surfaces: 'accented',
 	}),
 });
 
@@ -99,29 +49,42 @@ export const themePresetDefinitions = Object.freeze({
 	portfolio: Object.freeze({
 		title: 'Portfolio',
 		description: 'For portfolios and image-led sites, with restrained typography and generous space for images.',
-		theme: themePresetConfigurations.portfolio,
+		recipe: themePresetRecipes.portfolio,
+		readerControls: Object.freeze({ colorMode: true }),
 	}),
 	documentation: Object.freeze({
 		title: 'Documentation',
 		description: 'For guides and reference material, with reading-focused typography and compact spacing.',
-		theme: themePresetConfigurations.documentation,
+		recipe: themePresetRecipes.documentation,
+		readerControls: Object.freeze({ colorMode: true, focusReading: true }),
 	}),
 	project: Object.freeze({
 		title: 'Project',
 		description: 'For project and product sites that balance explanation, code, cards, and images.',
-		theme: themePresetConfigurations.project,
+		recipe: themePresetRecipes.project,
+		readerControls: Object.freeze({ colorMode: true, focusReading: true }),
 	}),
 	statement: Object.freeze({
 		title: 'Statement',
 		description: 'For short, expressive sites, with larger typography, airy spacing, and stronger section emphasis.',
-		theme: themePresetConfigurations.statement,
+		recipe: themePresetRecipes.statement,
+		readerControls: Object.freeze({ colorMode: true }),
 	}),
 });
 
 export const themePresetNames = Object.freeze(Object.keys(themePresetDefinitions));
 
 export const themePresets = Object.freeze(Object.fromEntries(
-	themePresetNames.map((name) => [name, themePresetDefinitions[name].theme]),
+	themePresetNames.map((name) => [
+		name,
+		freezeDeep({
+			...resolveThemeProfileRecipe(
+				themePresetDefinitions[name].recipe,
+				`${name} theme preset`,
+			),
+			readerControls: themePresetDefinitions[name].readerControls,
+		}),
+	]),
 ));
 
 export const getThemePresetMetadata = (presetName) => {
@@ -158,6 +121,30 @@ export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.yaml') => {
 	};
 };
 
+const mergePageThemePart = (base, override, keys) => Object.fromEntries(keys
+	.filter((key) => override?.[key] !== undefined || base?.[key] !== undefined)
+	.map((key) => [key, override?.[key] ?? base?.[key]]));
+
+export const mergePageThemeConfig = (base = {}, override = {}) => ({
+	...base,
+	layout: {
+		...(base.layout ?? {}),
+		...mergePageThemePart(base.layout, override.layout, ['contentSpacing', 'textWidth']),
+	},
+	images: {
+		...(base.images ?? {}),
+		...mergePageThemePart(base.images, override.images, [
+			'width',
+			'maxAvailableWidthPercent',
+			'maxAvailableHeightPercent',
+		]),
+	},
+	sections: {
+		...(base.sections ?? {}),
+		...mergePageThemePart(base.sections, override.sections, ['backgroundPattern']),
+	},
+});
+
 const quote = (value) => JSON.stringify(value);
 const responsiveValueLines = (label, value, indent = 2) => {
 	const prefix = ' '.repeat(indent);
@@ -171,7 +158,7 @@ const responsiveValueLines = (label, value, indent = 2) => {
 export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
 	const metadata = getThemePresetMetadata(presetName);
-	const { navigation, layout, images, typography, palette, sectionSurfaces } = preset;
+	const { colorMode, readerControls, corners, layout, images, blocks, typography, palette, sections } = preset;
 
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
@@ -181,13 +168,23 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		`# Available theme presets: ${themePresetNames.join(', ')}.`,
 		`preset: ${presetName}`,
 		'',
-		'navigation:',
-		'  # Alternatives: automatic, sections, top, tree.',
-		`  mode: ${navigation.mode}`,
+		'# Initial appearance. System follows the visitor\'s operating-system preference.',
+		'colorMode:',
+		`  default: ${colorMode.default}`,
+		'',
+		'# Optional reader controls shown with the always-available reading-width choice.',
+		'readerControls:',
+		`  colorMode: ${readerControls.colorMode === true}`,
+		`  focusReading: ${readerControls.focusReading === true}`,
+		'',
+		'# Alternatives: square, rounded.',
+		`corners: ${corners}`,
 		'',
 		'layout:',
-		'  # Alternatives: compact, normal, airy.',
-		`  density: ${layout.density}`,
+		'  # Alternatives: compact, normal, spacious.',
+		`  contentSpacing: ${layout.contentSpacing}`,
+		'  # Alternatives: narrow, normal, wide.',
+		`  textWidth: ${layout.textWidth}`,
 		'  # Any positive CSS length, including px, rem, em, %, or clamp(...).',
 		`  pageWidth: ${layout.pageWidth}`,
 		'  gutter:',
@@ -203,6 +200,12 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		...responsiveValueLines('maxAvailableWidthPercent', images.maxAvailableWidthPercent),
 		...responsiveValueLines('maxAvailableHeightPercent', images.maxAvailableHeightPercent),
 		'',
+		'blocks:',
+		'  cardList:',
+		'    # Alternatives: text, narrow, normal, wide.',
+		'    # A width written in a norna-card-list block overrides this default.',
+		`    width: ${blocks.cardList.width}`,
+		'',
 		'typography:',
 		'  # Any valid CSS font-family stack without semicolons.',
 		`  fontFamily: ${quote(typography.fontFamily)}`,
@@ -217,11 +220,12 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'  #     h2:',
 		'  #       size: large  # small, medium, large, or xlarge',
 		'',
-		'# Alternatives: dark, light, paper.',
+		`# Alternatives: ${presentationPaletteNames.join(', ')}.`,
 		`palette: ${palette}`,
-		'# One value keeps every section on the same surface; multiple values cycle.',
-		'# Use one to three unique values from: base, soft, emphasis.',
-		`sectionSurfaces: [${sectionSurfaces.join(', ')}]`,
+		'sections:',
+		'  # Alternatives: uniform, alternating, accented.',
+		'  # Alternating and accented are full-width and unavailable with tree navigation.',
+		`  backgroundPattern: ${sections.backgroundPattern}`,
 		'',
 	].join('\n');
 };