@janga/norna 0.7.9 → 0.7.11

package/scripts/lib/sitewide-config.mjs

@@ -0,0 +1,34 @@
+import { readFile } from 'node:fs/promises';
+import { parseYamlMapping } from './frontmatter-yaml.mjs';
+import {
+	sitewideContentLabel,
+	sitewideContentPath,
+} from './site-paths.mjs';
+import {
+	splitSiteFile,
+	validateFrontmatterIndentation,
+	validateSitewideFrontmatterStructure,
+} from './site-content.mjs';
+
+export const readSitewideConfig = async () => {
+	const source = await readFile(sitewideContentPath, 'utf8').catch((error) => {
+		if (error?.code === 'ENOENT') return null;
+		throw error;
+	});
+
+	if (!source) return {};
+
+	const { frontmatter, frontmatterBody } = splitSiteFile(source, sitewideContentLabel);
+	const issues = [];
+	validateFrontmatterIndentation(frontmatter, (issue) => issues.push(issue));
+	validateSitewideFrontmatterStructure(frontmatter, (issue) => issues.push(issue));
+
+	if (issues.length > 0) {
+		throw new Error([
+			`${sitewideContentLabel} has invalid frontmatter.`,
+			...issues.map((issue) => `- ${issue.message}`),
+		].join('\n'));
+	}
+
+	return parseYamlMapping(frontmatterBody);
+};

package/scripts/lib/theme-config.mjs

@@ -1,19 +1,25 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
 import { parseYamlMapping } from './frontmatter-yaml.mjs';
 import {
 	splitSiteFile,
-	validateFrontmatterColorValues,
 	validateFrontmatterIndentation,
+	validateRouteThemeFrontmatterStructure,
 	validateThemeFrontmatterStructure,
 } from './site-content.mjs';
-import { siteThemeLabel, siteThemePath } from './site-paths.mjs';
-
-const emptyThemeFile = '---\n---\n';
+import {
+	siteRoutesDir,
+	siteRoutesLabel,
+	siteThemeLabel,
+	siteThemePath,
+	sitewideContentLabel,
+} from './site-paths.mjs';
+import { resolveThemeConfig } from './theme-presets.mjs';
 
 export const readThemeConfig = async () => {
 	const themeFile = await readFile(siteThemePath, 'utf8').catch((error) => {
 		if (error?.code === 'ENOENT') {
-			return emptyThemeFile;
+			throw new Error(`${siteThemeLabel} is required. Create it before running Norna.`);
 		}
 
 		throw error;
@@ -23,7 +29,6 @@ export const readThemeConfig = async () => {
 
 	validateFrontmatterIndentation(frontmatter, (issue) => issues.push(issue));
 	validateThemeFrontmatterStructure(frontmatter, (issue) => issues.push(issue));
-	validateFrontmatterColorValues(frontmatter, (issue) => issues.push(issue), siteThemeLabel);
 
 	if (issues.length > 0) {
 		throw new Error([
@@ -32,5 +37,67 @@ export const readThemeConfig = async () => {
 		].join('\n'));
 	}
 
-	return parseYamlMapping(frontmatterBody);
+	const config = parseYamlMapping(frontmatterBody);
+	if (Object.hasOwn(config, 'navigation')) {
+		throw new Error(`${siteThemeLabel} may not define navigation. Brand and logo belong in ${sitewideContentLabel}.`);
+	}
+	resolveThemeConfig(config, siteThemeLabel);
+
+	return config;
+};
+
+const getRouteThemeFiles = async (directory, relativeDirectory = '') => {
+	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+		if (error?.code === 'ENOENT') return [];
+		throw error;
+	});
+	const files = [];
+
+	for (const entry of entries) {
+		const relativePath = path.join(relativeDirectory, entry.name);
+		const absolutePath = path.join(directory, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...await getRouteThemeFiles(absolutePath, relativePath));
+			continue;
+		}
+
+		if (entry.name === 'theme.md') {
+			files.push({
+				path: absolutePath,
+				label: `${siteRoutesLabel}/${relativePath.split(path.sep).join('/')}`,
+			});
+		}
+	}
+
+	return files;
+};
+
+export const validateRouteThemeFiles = async () => {
+	const files = await getRouteThemeFiles(siteRoutesDir);
+	const configs = [];
+
+	for (const file of files) {
+		const source = await readFile(file.path, 'utf8');
+		const { frontmatter, frontmatterBody } = splitSiteFile(source, file.label);
+		const issues = [];
+		validateFrontmatterIndentation(frontmatter, (issue) => issues.push(issue));
+		validateRouteThemeFrontmatterStructure(frontmatter, (issue) => issues.push(issue));
+
+		if (issues.length > 0) {
+			throw new Error([
+				`${file.label} has invalid frontmatter.`,
+				...issues.map((issue) => `- ${issue.message}`),
+			].join('\n'));
+		}
+
+		const config = parseYamlMapping(frontmatterBody);
+		if (Object.hasOwn(config, 'navigation')) {
+			throw new Error(`${file.label} may not define navigation. Brand and logo belong in ${sitewideContentLabel}.`);
+		}
+		resolveThemeConfig(config, file.label);
+
+		configs.push({ ...file, config });
+	}
+
+	return configs;
 };

package/scripts/lib/theme-presets.mjs

@@ -0,0 +1,209 @@
+import { mergeDeep } from './typography.mjs';
+
+export const themePresetNames = [
+	'portfolio',
+	'documentation',
+	'project',
+	'statement',
+];
+
+export const themePresets = Object.freeze({
+	portfolio: Object.freeze({
+		layout: {
+			density: 'normal',
+			pageWidth: '1240px',
+			gutter: {
+				desktop: 'clamp(1.25rem, 4vw, 3rem)',
+				mobile: '1rem',
+			},
+		},
+		gallery: {
+			width: '1000px',
+			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+			maxAvailableHeightPercent: { desktop: 78, mobile: 68 },
+		},
+		typography: {
+			fontFamily: "'Helvetica Neue', Arial, sans-serif",
+			preset: 'quiet-gallery',
+			rhythm: 'normal',
+		},
+		presentation: {
+			palette: 'dark',
+			sectionSurfaces: {
+				mode: 'none',
+				sequence: ['base', 'soft', 'emphasis'],
+			},
+		},
+	}),
+	documentation: Object.freeze({
+		layout: {
+			density: 'compact',
+			pageWidth: '1240px',
+			gutter: {
+				desktop: 'clamp(1.25rem, 4vw, 3rem)',
+				mobile: '1rem',
+			},
+		},
+		gallery: {
+			width: '920px',
+			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+			maxAvailableHeightPercent: { desktop: 74, mobile: 68 },
+		},
+		typography: {
+			fontFamily: "Georgia, 'Times New Roman', serif",
+			preset: 'text-forward',
+			rhythm: 'compact',
+		},
+		presentation: {
+			palette: 'paper',
+			sectionSurfaces: {
+				mode: 'cycle',
+				sequence: ['base', 'soft'],
+			},
+		},
+	}),
+	project: Object.freeze({
+		layout: {
+			density: 'compact',
+			pageWidth: '1120px',
+			gutter: {
+				desktop: 'clamp(1.25rem, 4vw, 3rem)',
+				mobile: '1rem',
+			},
+		},
+		gallery: {
+			width: '840px',
+			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+			maxAvailableHeightPercent: { desktop: 70, mobile: 62 },
+		},
+		typography: {
+			fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+			preset: 'text-forward',
+			rhythm: 'compact',
+		},
+		presentation: {
+			palette: 'light',
+			sectionSurfaces: {
+				mode: 'cycle',
+				sequence: ['base', 'soft'],
+			},
+		},
+	}),
+	statement: Object.freeze({
+		layout: {
+			density: 'airy',
+			pageWidth: '1280px',
+			gutter: {
+				desktop: 'clamp(1.5rem, 5vw, 4rem)',
+				mobile: '1rem',
+			},
+		},
+		gallery: {
+			width: '1080px',
+			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+			maxAvailableHeightPercent: { desktop: 80, mobile: 70 },
+		},
+		typography: {
+			fontFamily: "'Trebuchet MS', 'Helvetica Neue', Arial, sans-serif",
+			preset: 'statement',
+			rhythm: 'airy',
+		},
+		presentation: {
+			palette: 'paper',
+			sectionSurfaces: {
+				mode: 'cycle',
+				sequence: ['base', 'emphasis'],
+			},
+		},
+	}),
+});
+
+export const getThemePreset = (presetName, sourceLabel = 'theme.md') => {
+	const preset = themePresets[presetName];
+
+	if (!preset) {
+		throw new Error(`Unknown theme preset "${presetName}" in ${sourceLabel}. Use one of: ${themePresetNames.join(', ')}.`);
+	}
+
+	return structuredClone(preset);
+};
+
+export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.md') => {
+	const presetName = theme?.preset;
+	if (presetName === undefined) return structuredClone(theme ?? {});
+
+	const overrides = structuredClone(theme ?? {});
+	delete overrides.preset;
+
+	return {
+		preset: presetName,
+		...mergeDeep(getThemePreset(presetName, sourceLabel), overrides),
+	};
+};
+
+const quote = (value) => JSON.stringify(value);
+const responsiveValueLines = (label, value, indent = 2) => {
+	const prefix = ' '.repeat(indent);
+	return [
+		`${prefix}${label}:`,
+		`${prefix}  desktop: ${value.desktop}`,
+		`${prefix}  mobile: ${value.mobile}`,
+	];
+};
+
+export const renderThemePresetReference = (presetName, sourceLabel = 'theme.md') => {
+	const preset = getThemePreset(presetName, sourceLabel);
+	const { layout, gallery, typography, presentation } = preset;
+
+	return [
+		'---',
+		`# Original values for Norna's "${presetName}" theme preset.`,
+		'# This is a reference file. Norna only loads theme.md.',
+		'# Keep the preset in theme.md and copy only the values you want to override.',
+		`# Available theme presets: ${themePresetNames.join(', ')}.`,
+		`preset: ${presetName}`,
+		'',
+		'layout:',
+		'  # Alternatives: compact, normal, airy.',
+		`  density: ${layout.density}`,
+		'  # Any positive CSS length, including px, rem, em, %, or clamp(...).',
+		`  pageWidth: ${layout.pageWidth}`,
+		'  gutter:',
+		`    desktop: ${layout.gutter.desktop}`,
+		`    mobile: ${layout.gutter.mobile}`,
+		'  # Optional spacing overrides use blockGap, finalSectionBottom,',
+		'  # firstSectionTop, headingToBlock, imageGap, and sectionGap.',
+		'',
+		'gallery:',
+		'  # width accepts a positive CSS length.',
+		`  width: ${gallery.width}`,
+		'  # Percent values must be greater than 0 and at most 100.',
+		...responsiveValueLines('maxAvailableWidthPercent', gallery.maxAvailableWidthPercent),
+		...responsiveValueLines('maxAvailableHeightPercent', gallery.maxAvailableHeightPercent),
+		'',
+		'typography:',
+		'  # Any valid CSS font-family stack without semicolons.',
+		`  fontFamily: ${quote(typography.fontFamily)}`,
+		'  # Alternatives: quiet-gallery, compact-gallery, text-forward, statement.',
+		`  preset: ${typography.preset}`,
+		'  # Alternatives: compact, normal, airy.',
+		`  rhythm: ${typography.rhythm}`,
+		'  # Fine-grained overrides can target headings.h1-h4, body, and caption.',
+		'  # Example:',
+		'  # overrides:',
+		'  #   headings:',
+		'  #     h2:',
+		'  #       size: large  # small, medium, large, or xlarge',
+		'',
+		'presentation:',
+		'  # Alternatives: dark, light, paper.',
+		`  palette: ${presentation.palette}`,
+		'  sectionSurfaces:',
+		'    # Alternatives: none, cycle.',
+		`    mode: ${presentation.sectionSurfaces.mode}`,
+		'    # Use one to three unique values from: base, soft, emphasis.',
+		`    sequence: [${presentation.sectionSurfaces.sequence.join(', ')}]`,
+		'---',
+		'',
+	].join('\n');
+};

package/scripts/lib/typography.mjs

@@ -17,27 +17,32 @@ export const typographyPresets = {
 			h1: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 400,
 				lineHeight: 1.04,
 			},
 			h2: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 400,
 				lineHeight: 1.08,
 			},
 			h3: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 500,
 				lineHeight: 1.35,
 			},
 			h4: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 400,
 				lineHeight: 1.5,
 			},
 		},
 		body: {
 			align: { desktop: 'left', mobile: 'left' },
 			size: 'medium',
+			width: 'normal',
 			lineHeight: 1.5,
 		},
 		caption: {
@@ -51,27 +56,32 @@ export const typographyPresets = {
 			h1: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 500,
 				lineHeight: 1.04,
 			},
 			h2: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 500,
 				lineHeight: 1.08,
 			},
 			h3: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 600,
 				lineHeight: 1.3,
 			},
 			h4: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 500,
 				lineHeight: 1.42,
 			},
 		},
 		body: {
 			align: { desktop: 'left', mobile: 'left' },
 			size: 'medium',
+			width: 'wide',
 			lineHeight: 1.42,
 		},
 		caption: {
@@ -85,27 +95,32 @@ export const typographyPresets = {
 			h1: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 500,
 				lineHeight: 1.06,
 			},
 			h2: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 500,
 				lineHeight: 1.12,
 			},
 			h3: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 500,
 				lineHeight: 1.35,
 			},
 			h4: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 400,
 				lineHeight: 1.55,
 			},
 		},
 		body: {
 			align: { desktop: 'left', mobile: 'left' },
 			size: 'medium',
+			width: 'narrow',
 			lineHeight: 1.62,
 		},
 		caption: {
@@ -119,27 +134,32 @@ export const typographyPresets = {
 			h1: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 600,
 				lineHeight: 1.02,
 			},
 			h2: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 600,
 				lineHeight: 1.04,
 			},
 			h3: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 600,
 				lineHeight: 1.18,
 			},
 			h4: {
 				align: { desktop: 'left', mobile: 'left' },
 				size: 'medium',
+				weight: 500,
 				lineHeight: 1.42,
 			},
 		},
 		body: {
 			align: { desktop: 'left', mobile: 'left' },
 			size: 'medium',
+			width: 'narrow',
 			lineHeight: 1.42,
 		},
 		caption: {
@@ -243,32 +263,6 @@ export const resolveTypographyConfig = (typography = defaultTypography) => {
 	};
 };
 
-export const resolveTypographyOverride = (baseResolved, typographyConfig) => {
-	if (typographyConfig?.preset || typographyConfig?.rhythm) {
-		return resolveTypographyConfig({
-			preset: typographyConfig.preset ?? baseResolved.preset,
-			rhythm: typographyConfig.rhythm ?? baseResolved.rhythm,
-			overrides: typographyConfig.overrides,
-		});
-	}
-
-	if (typographyConfig?.overrides) {
-		return {
-			preset: baseResolved.preset,
-			rhythm: baseResolved.rhythm,
-			values: mergeDeep(baseResolved.values, typographyConfig.overrides),
-		};
-	}
-
-	return baseResolved;
-};
-
-export const resolveSectionTypography = (defaultTypographyConfig, sectionTypographyConfig) => {
-	const defaultResolved = resolveTypographyConfig(defaultTypographyConfig);
-
-	return resolveTypographyOverride(defaultResolved, sectionTypographyConfig);
-};
-
 const quoteString = (value) => typeof value === 'string' && !/^[a-z0-9.-]+$/i.test(value)
 	? JSON.stringify(value)
 	: value;