@janga/norna 0.7.18 → 0.7.23

package/scripts/lib/typography.mjs

@@ -1,16 +1,223 @@
-export const typographyProfileNames = [
-	'restrained',
-	'dense',
-	'reading',
-	'statement',
-];
+import { isPlainObject, mergeDeep } from './object.mjs';
 
-export const typographyRhythmNames = [
-	'compact',
-	'normal',
-	'airy',
+export const typographySizeNames = [
+	'small',
+	'medium',
+	'large',
+	'xlarge',
 ];
 
+export const headingTypographySizeValues = {
+	h1: {
+		small: {
+			desktop: 'clamp(1.35rem, 1.2rem + 0.55vw, 1.7rem)',
+			mobile: 'clamp(1.32rem, 1.16rem + 0.8vw, 1.58rem)',
+		},
+		medium: {
+			desktop: 'clamp(1.65rem, 1.35rem + 1.1vw, 2.4rem)',
+			mobile: 'clamp(1.5rem, 1.22rem + 1.4vw, 2rem)',
+		},
+		large: {
+			desktop: 'clamp(1.95rem, 1.48rem + 1.7vw, 3.2rem)',
+			mobile: 'clamp(1.75rem, 1.32rem + 2.15vw, 2.5rem)',
+		},
+		xlarge: {
+			desktop: 'clamp(2.35rem, 1.58rem + 2.75vw, 4.4rem)',
+			mobile: 'clamp(2rem, 1.4rem + 3vw, 3.1rem)',
+		},
+	},
+	h2: {
+		small: {
+			desktop: 'clamp(1.1rem, 1.02rem + 0.35vw, 1.35rem)',
+			mobile: 'clamp(1.12rem, 1rem + 0.85vw, 1.42rem)',
+		},
+		medium: {
+			desktop: 'clamp(1.35rem, 1.1rem + 0.9vw, 2rem)',
+			mobile: 'clamp(1.3rem, 1.05rem + 1.35vw, 1.75rem)',
+		},
+		large: {
+			desktop: 'clamp(1.6rem, 1.22rem + 1.45vw, 2.75rem)',
+			mobile: 'clamp(1.5rem, 1.12rem + 2vw, 2.25rem)',
+		},
+		xlarge: {
+			desktop: 'clamp(2rem, 1.35rem + 2.4vw, 3.75rem)',
+			mobile: 'clamp(1.8rem, 1.25rem + 3vw, 2.85rem)',
+		},
+	},
+	h3: {
+		small: {
+			desktop: 'clamp(0.96rem, 0.94rem + 0.08vw, 1rem)',
+			mobile: 'clamp(0.96rem, 0.94rem + 0.08vw, 1rem)',
+		},
+		medium: {
+			desktop: 'clamp(1.05rem, 0.98rem + 0.28vw, 1.22rem)',
+			mobile: 'clamp(1.04rem, 0.98rem + 0.45vw, 1.18rem)',
+		},
+		large: {
+			desktop: 'clamp(1.16rem, 1.02rem + 0.5vw, 1.5rem)',
+			mobile: 'clamp(1.12rem, 1rem + 0.75vw, 1.36rem)',
+		},
+		xlarge: {
+			desktop: 'clamp(1.32rem, 1.08rem + 0.85vw, 1.9rem)',
+			mobile: 'clamp(1.24rem, 1.04rem + 1.15vw, 1.65rem)',
+		},
+	},
+	h4: {
+		small: {
+			desktop: 'clamp(0.86rem, 0.84rem + 0.08vw, 0.92rem)',
+			mobile: 'clamp(0.86rem, 0.84rem + 0.08vw, 0.92rem)',
+		},
+		medium: {
+			desktop: 'clamp(0.96rem, 0.94rem + 0.08vw, 1rem)',
+			mobile: 'clamp(0.96rem, 0.94rem + 0.08vw, 1rem)',
+		},
+		large: {
+			desktop: 'clamp(1.05rem, 1rem + 0.16vw, 1.12rem)',
+			mobile: 'clamp(1.05rem, 1rem + 0.16vw, 1.12rem)',
+		},
+		xlarge: {
+			desktop: 'clamp(1.14rem, 1.06rem + 0.26vw, 1.25rem)',
+			mobile: 'clamp(1.14rem, 1.06rem + 0.26vw, 1.25rem)',
+		},
+	},
+};
+
+export const bodyTypographySizeValues = {
+	small: {
+		desktop: 'clamp(0.86rem, 0.84rem + 0.08vw, 0.92rem)',
+		mobile: 'clamp(0.86rem, 0.84rem + 0.08vw, 0.92rem)',
+	},
+	medium: {
+		desktop: 'clamp(0.96rem, 0.94rem + 0.08vw, 1rem)',
+		mobile: 'clamp(0.96rem, 0.94rem + 0.08vw, 1rem)',
+	},
+	large: {
+		desktop: 'clamp(1.05rem, 1rem + 0.16vw, 1.12rem)',
+		mobile: 'clamp(1.05rem, 1rem + 0.16vw, 1.12rem)',
+	},
+	xlarge: {
+		desktop: 'clamp(1.14rem, 1.06rem + 0.26vw, 1.25rem)',
+		mobile: 'clamp(1.14rem, 1.06rem + 0.26vw, 1.25rem)',
+	},
+};
+
+export const captionTypographySizeValues = {
+	small: {
+		desktop: 'clamp(0.78rem, 0.76rem + 0.08vw, 0.84rem)',
+		mobile: 'clamp(0.78rem, 0.76rem + 0.08vw, 0.84rem)',
+	},
+	medium: {
+		desktop: 'clamp(0.86rem, 0.84rem + 0.08vw, 0.92rem)',
+		mobile: 'clamp(0.86rem, 0.84rem + 0.08vw, 0.92rem)',
+	},
+	large: {
+		desktop: 'clamp(0.96rem, 0.92rem + 0.12vw, 1rem)',
+		mobile: 'clamp(0.96rem, 0.92rem + 0.12vw, 1rem)',
+	},
+	xlarge: {
+		desktop: 'clamp(1.04rem, 0.98rem + 0.18vw, 1.12rem)',
+		mobile: 'clamp(1.04rem, 0.98rem + 0.18vw, 1.12rem)',
+	},
+};
+
+export const getTypographySizeValue = (sizeValues, size) => sizeValues[size];
+export const getHeadingTypographySizeValue = (level, size) => (
+	headingTypographySizeValues[level][size]
+);
+
+const headingLevels = Object.freeze(['h1', 'h2', 'h3', 'h4']);
+const textWidthNames = Object.freeze(['narrow', 'normal', 'wide']);
+const responsiveModes = Object.freeze({
+	mobile: Object.freeze({ from: 320, to: 700 }),
+	desktop: Object.freeze({ from: 701, to: 2560 }),
+});
+const responsiveClampPattern = /^clamp\(([\d.]+)rem,\s*([\d.]+)rem\s*\+\s*([\d.]+)vw,\s*([\d.]+)rem\)$/u;
+const parsedResponsiveSizes = new Map();
+const validatedTypographySignatures = new Set();
+
+const evaluateResponsiveSize = (value, viewportWidth) => {
+	let parsed = parsedResponsiveSizes.get(value);
+	if (!parsed) {
+		const match = value.match(responsiveClampPattern);
+		if (!match) {
+			throw new Error(`Cannot validate unsupported responsive typography size: ${value}`);
+		}
+
+		const [, minimumRem, baseRem, viewportWidthFactor, maximumRem] = match.map(Number);
+		parsed = { minimumRem, baseRem, viewportWidthFactor, maximumRem };
+		parsedResponsiveSizes.set(value, parsed);
+	}
+
+	const preferredPixels = (parsed.baseRem * 16) + ((parsed.viewportWidthFactor / 100) * viewportWidth);
+	return Math.min(parsed.maximumRem * 16, Math.max(parsed.minimumRem * 16, preferredPixels));
+};
+
+export const assertTypographyContract = (typography, sourceLabel = 'theme.yaml') => {
+	const values = typography?.values ?? typography;
+	if (!values?.headings || !values?.body || !values?.caption) {
+		throw new Error(`Incomplete typography configuration in ${sourceLabel}.`);
+	}
+
+	for (const level of headingLevels) {
+		const heading = values.headings[level];
+		if (!heading || !typographySizeNames.includes(heading.size)) {
+			throw new Error(`${level}.size must be one of ${typographySizeNames.join(', ')} in ${sourceLabel}.`);
+		}
+		if (!Number.isFinite(heading.lineHeight) || heading.lineHeight < 1) {
+			throw new Error(`${level}.lineHeight must be at least 1 in ${sourceLabel}.`);
+		}
+	}
+
+	if (!typographySizeNames.includes(values.body.size)) {
+		throw new Error(`body.size must be one of ${typographySizeNames.join(', ')} in ${sourceLabel}.`);
+	}
+	if (!textWidthNames.includes(values.body.width)) {
+		throw new Error(`body.width must be one of ${textWidthNames.join(', ')} in ${sourceLabel}.`);
+	}
+	if (!Number.isFinite(values.body.lineHeight) || values.body.lineHeight < 1.4) {
+		throw new Error(`body.lineHeight must be at least 1.4 in ${sourceLabel}.`);
+	}
+	if (!typographySizeNames.includes(values.caption.size)) {
+		throw new Error(`caption.size must be one of ${typographySizeNames.join(', ')} in ${sourceLabel}.`);
+	}
+	if (!Number.isFinite(values.caption.lineHeight) || values.caption.lineHeight < 1.25) {
+		throw new Error(`caption.lineHeight must be at least 1.25 in ${sourceLabel}.`);
+	}
+	const signature = JSON.stringify({
+		body: { lineHeight: values.body.lineHeight, size: values.body.size, width: values.body.width },
+		caption: { lineHeight: values.caption.lineHeight, size: values.caption.size },
+		headings: Object.fromEntries(headingLevels.map((level) => [level, {
+			lineHeight: values.headings[level].lineHeight,
+			size: values.headings[level].size,
+		}])),
+	});
+	if (validatedTypographySignatures.has(signature)) return typography;
+
+	for (const [mode, range] of Object.entries(responsiveModes)) {
+		for (let viewportWidth = range.from; viewportWidth <= range.to; viewportWidth += 1) {
+			const sizes = headingLevels.map((level) => evaluateResponsiveSize(
+				headingTypographySizeValues[level][values.headings[level].size][mode],
+				viewportWidth,
+			));
+
+			for (let index = 0; index < headingLevels.length - 1; index += 1) {
+				if (sizes[index] <= sizes[index + 1]) {
+					const currentLevel = headingLevels[index];
+					const nextLevel = headingLevels[index + 1];
+					throw new Error([
+						`Typography must preserve ${currentLevel.toUpperCase()} > ${nextLevel.toUpperCase()} in ${sourceLabel}.`,
+						`The selected sizes ${values.headings[currentLevel].size} and ${values.headings[nextLevel].size}`,
+						`cross at ${viewportWidth}px in the ${mode} scale.`,
+					].join(' '));
+				}
+			}
+		}
+	}
+	validatedTypographySignatures.add(signature);
+
+	return typography;
+};
+
 export const typographyProfiles = {
 	restrained: {
 		headings: {
@@ -220,29 +427,7 @@ export const defaultTypography = {
 	rhythm: 'normal',
 };
 
-const isPlainObject = (value) => (
-	value !== null &&
-	typeof value === 'object' &&
-	!Array.isArray(value)
-);
-
-export const mergeDeep = (base, override) => {
-	if (!isPlainObject(override)) return structuredClone(base);
-
-	const merged = structuredClone(base);
-
-	for (const [key, value] of Object.entries(override)) {
-		if (isPlainObject(value) && isPlainObject(merged[key])) {
-			merged[key] = mergeDeep(merged[key], value);
-		} else if (value !== undefined) {
-			merged[key] = value;
-		}
-	}
-
-	return merged;
-};
-
-export const resolveTypographyConfig = (typography = defaultTypography) => {
+export const resolveTypographyConfig = (typography = defaultTypography, sourceLabel = 'theme.yaml') => {
 	const profileName = typography?.profile ?? defaultTypography.profile;
 	const rhythmName = typography?.rhythm ?? defaultTypography.rhythm;
 	const profile = typographyProfiles[profileName];
@@ -256,11 +441,11 @@ export const resolveTypographyConfig = (typography = defaultTypography) => {
 		throw new Error(`Unknown typography rhythm: ${rhythmName}`);
 	}
 
-	return {
+	return assertTypographyContract({
 		profile: profileName,
 		rhythm: rhythmName,
 		values: mergeDeep(mergeDeep(profile, rhythm), typography?.overrides),
-	};
+	}, sourceLabel);
 };
 
 const quoteString = (value) => typeof value === 'string' && !/^[a-z0-9.-]+$/i.test(value)

package/scripts/lib/yaml-config.mjs

@@ -1,11 +1,55 @@
 import { load } from 'js-yaml';
 import {
-	validateFrontmatterIndentation,
-} from './site-content.mjs';
+	validateYamlIndentation,
+} from './yaml-indentation.mjs';
 
-const formatSchemaIssues = (issues) => issues.map((issue) => {
+const getValueAtPath = (data, path) => path.reduce(
+	(value, key) => value?.[key],
+	data,
+);
+
+const getLegacyThemeHint = (issue, data) => {
+	const location = issue.path.join('.');
+	const value = getValueAtPath(data, issue.path);
+
+	if (location === 'palette') {
+		const replacements = {
+			dark: 'near-monochrome',
+			light: 'arctic-blue',
+			paper: 'warm-paper',
+			'cool-green': 'arctic-blue',
+		};
+		if (replacements[value]) {
+			return `Palette value "${value}" was replaced by "${replacements[value]}".`;
+		}
+	}
+
+	if (location === 'corners' && value === 'soft') {
+		return 'Corner value "soft" was replaced by "rounded".';
+	}
+
+	if (location === 'sections.backgroundPattern' && value === 'cycling') {
+		return 'Section background pattern "cycling" was replaced by "accented".';
+	}
+
+	if (location === '' && issue.keys?.includes('colorMode')) {
+		return 'Theme setting "colorMode" was replaced by "appearance".';
+	}
+
+	if (location === 'readerControls' && issue.keys?.includes('colorMode')) {
+		return 'Reader control "colorMode" was replaced by "appearance".';
+	}
+
+	if (location === 'readerControls' && issue.keys?.includes('readingWidth')) {
+		return 'Reader control "readingWidth" was removed because reading width is now always available. Remove this field.';
+	}
+
+	return undefined;
+};
+
+const formatSchemaIssues = (issues, data) => issues.map((issue) => {
 	const location = issue.path.join('.') || '(root)';
-	return `- ${location}: ${issue.message}`;
+	return `- ${location}: ${getLegacyThemeHint(issue, data) ?? issue.message}`;
 });
 
 export const parseYamlConfig = (source, label, {
@@ -14,7 +58,7 @@ export const parseYamlConfig = (source, label, {
 } = {}) => {
 	const issues = [];
 
-	validateFrontmatterIndentation(source, (issue) => issues.push(issue));
+	validateYamlIndentation(source, (issue) => issues.push(issue));
 	validateStructure?.(source, (issue) => issues.push(issue));
 
 	if (issues.length > 0) {
@@ -42,7 +86,7 @@ export const parseYamlConfig = (source, label, {
 	if (!parsed.success) {
 		throw new Error([
 			`${label} has invalid values.`,
-			...formatSchemaIssues(parsed.error.issues),
+			...formatSchemaIssues(parsed.error.issues, data),
 		].join('\n'));
 	}
 

package/scripts/lib/yaml-indentation.mjs

@@ -0,0 +1,86 @@
+const yamlDelimiterRegex = /^---\s*$/;
+
+export 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 getNextYamlEntry = (lines, startIndex) => {
+	for (let index = startIndex + 1; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (!line.trim() || line.trim().startsWith('#') || yamlDelimiterRegex.test(line)) {
+			continue;
+		}
+
+		return {
+			index,
+			line,
+			...getIndentInfo(line),
+		};
+	}
+
+	return null;
+};
+
+export const validateYamlIndentation = (source, addIssue) => {
+	const lines = source.split(/\r?\n/);
+
+	for (const [index, line] of lines.entries()) {
+		const lineNumber = index + 1;
+		const trimmed = line.trim();
+
+		if (!trimmed || trimmed.startsWith('#') || yamlDelimiterRegex.test(line)) {
+			continue;
+		}
+
+		const { indent, hasInvalidWhitespace } = getIndentInfo(line);
+
+		if (hasInvalidWhitespace) {
+			addIssue({
+				severity: 'error',
+				message: `YAML 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: `YAML line ${lineNumber} is indented with ${indent} spaces.`,
+				fix: 'Use 2-space indentation levels in YAML.',
+			});
+		}
+
+		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 = getNextYamlEntry(lines, index);
+		if (!nextEntry || nextEntry.indent <= indent) continue;
+
+		addIssue({
+			severity: 'error',
+			message: `YAML 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.',
+		});
+	}
+};

package/scripts/show-typography.mjs

@@ -6,12 +6,12 @@ import {
 	typographyRhythms,
 } from './lib/typography.mjs';
 import {
-	getBodySections,
 	getContentFiles,
 	readSiteFile,
 	validateContentFrontmatterStructure,
 	validateFrontmatterIndentation,
 } from './lib/site-content.mjs';
+import { parsePageMarkdown } from './lib/page-markdown.mjs';
 import {
 	siteThemeLabel,
 } from './lib/site-paths.mjs';
@@ -202,8 +202,7 @@ const readPageTypography = async (contentFile, siteThemeTypography) => {
 	}
 
 	const pageTypography = siteThemeTypography;
-	const sections = (await getBodySections(body)).sections
-		.filter((section) => section.id)
+	const sections = (await parsePageMarkdown(body, { label: contentFile.contentLabel })).sections
 		.map((section) => {
 		return {
 			id: section.id,