@janga/norna 0.7.18 → 0.7.23

package/scripts/lib/theme-presets.mjs

@@ -1,105 +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({
-		shape: 'square',
-		layout: {
-			contentSpacing: 'normal',
-			textWidth: 'wide',
-			pageWidth: '1240px',
-			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
-			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',
-		sections: { backgroundPattern: 'uniform' },
+		color: 'near-monochrome-dark',
+		typography: 'restrained-sans',
+		rhythm: 'balanced',
+		geometry: 'image-led',
+		media: 'prominent',
+		blocks: 'wide-cards',
+		corners: 'square',
+		surfaces: 'uniform',
 	}),
 	documentation: Object.freeze({
-		shape: 'soft',
-		layout: {
-			contentSpacing: 'compact',
-			textWidth: 'narrow',
-			pageWidth: '1240px',
-			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
-			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',
-		sections: { backgroundPattern: 'alternating' },
+		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({
-		shape: 'soft',
-		layout: {
-			contentSpacing: 'compact',
-			textWidth: 'normal',
-			pageWidth: '1120px',
-			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
-			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',
-		sections: { backgroundPattern: 'alternating' },
+		color: 'near-monochrome-adaptive',
+		typography: 'system-reading',
+		rhythm: 'compact',
+		geometry: 'balanced-site',
+		media: 'balanced',
+		blocks: 'balanced-cards',
+		corners: 'rounded',
+		surfaces: 'alternating',
 	}),
 	statement: Object.freeze({
-		shape: 'square',
-		layout: {
-			contentSpacing: 'spacious',
-			textWidth: 'normal',
-			pageWidth: '1280px',
-			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
-			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',
-		sections: { backgroundPattern: 'cycling' },
+		color: 'warm-paper-adaptive',
+		typography: 'expressive-sans',
+		rhythm: 'expansive',
+		geometry: 'expansive-statement',
+		media: 'immersive',
+		blocks: 'wide-cards',
+		corners: 'square',
+		surfaces: 'accented',
 	}),
 });
 
@@ -107,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({ appearance: 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({ appearance: 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({ appearance: 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({ appearance: 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) => {
@@ -160,35 +115,56 @@ export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.yaml') => {
 	const overrides = structuredClone(theme ?? {});
 	delete overrides.preset;
 
-	return {
+	const resolved = {
 		preset: presetName,
 		...mergeDeep(getThemePreset(presetName, sourceLabel), overrides),
 	};
+
+	if (
+		overrides.images?.presentation === 'prose-aligned'
+		&& overrides.images.maxAvailableHeightPercent === undefined
+	) {
+		delete resolved.images.maxAvailableHeightPercent;
+	}
+
+	return resolved;
 };
 
 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: {
+export const mergePageThemeConfig = (base = {}, override = {}) => {
+	const images = {
 		...(base.images ?? {}),
 		...mergePageThemePart(base.images, override.images, [
+			'presentation',
 			'width',
 			'maxAvailableWidthPercent',
 			'maxAvailableHeightPercent',
 		]),
-	},
-	sections: {
-		...(base.sections ?? {}),
-		...mergePageThemePart(base.sections, override.sections, ['backgroundPattern']),
-	},
-});
+	};
+
+	if (
+		override.images?.presentation === 'prose-aligned'
+		&& override.images.maxAvailableHeightPercent === undefined
+	) {
+		delete images.maxAvailableHeightPercent;
+	}
+
+	return {
+		...base,
+		layout: {
+			...(base.layout ?? {}),
+			...mergePageThemePart(base.layout, override.layout, ['contentSpacing', 'textWidth']),
+		},
+		images,
+		sections: {
+			...(base.sections ?? {}),
+			...mergePageThemePart(base.sections, override.sections, ['backgroundPattern']),
+		},
+	};
+};
 
 const quote = (value) => JSON.stringify(value);
 const responsiveValueLines = (label, value, indent = 2) => {
@@ -203,7 +179,7 @@ const responsiveValueLines = (label, value, indent = 2) => {
 export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
 	const metadata = getThemePresetMetadata(presetName);
-	const { shape, layout, images, typography, palette, sections } = preset;
+	const { appearance, readerControls, corners, layout, images, blocks, typography, palette, sections } = preset;
 
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
@@ -213,8 +189,17 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		`# Available theme presets: ${themePresetNames.join(', ')}.`,
 		`preset: ${presetName}`,
 		'',
-		'# Alternatives: square, soft.',
-		`shape: ${shape}`,
+		'# Initial appearance. System follows the visitor\'s operating-system preference.',
+		'appearance:',
+		`  default: ${appearance.default}`,
+		'',
+		'# Optional reader controls shown with the always-available reading-width choice.',
+		'readerControls:',
+		`  appearance: ${readerControls.appearance === true}`,
+		`  focusReading: ${readerControls.focusReading === true}`,
+		'',
+		'# Alternatives: square, rounded.',
+		`corners: ${corners}`,
 		'',
 		'layout:',
 		'  # Alternatives: compact, normal, spacious.',
@@ -230,11 +215,24 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'  # firstSectionTop, headingToBlock, imageGap, and sectionGap.',
 		'',
 		'images:',
+		'  # Alternatives: prose-aligned, centered-fit.',
+		`  presentation: ${images.presentation}`,
 		'  # width accepts a positive CSS length.',
 		`  width: ${images.width}`,
 		'  # Percent values must be greater than 0 and at most 100.',
 		...responsiveValueLines('maxAvailableWidthPercent', images.maxAvailableWidthPercent),
-		...responsiveValueLines('maxAvailableHeightPercent', images.maxAvailableHeightPercent),
+		...(images.maxAvailableHeightPercent
+			? [
+				'  # Viewport-height limits apply only to centered-fit presentation.',
+				...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.',
@@ -250,10 +248,11 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'  #     h2:',
 		'  #       size: large  # small, medium, large, or xlarge',
 		'',
-		'# Alternatives: dark, light, paper.',
+		`# Alternatives: ${presentationPaletteNames.join(', ')}.`,
 		`palette: ${palette}`,
 		'sections:',
-		'  # Alternatives: uniform, alternating, cycling.',
+		'  # Alternatives: uniform, alternating, accented.',
+		'  # Alternating and accented are full-width and unavailable with tree navigation.',
 		`  backgroundPattern: ${sections.backgroundPattern}`,
 		'',
 	].join('\n');

package/scripts/lib/theme-profiles.mjs

@@ -0,0 +1,223 @@
+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',
+		},
+		'warm-paper-adaptive': {
+			appearance: { default: 'system' },
+			palette: 'warm-paper',
+		},
+	},
+	typography: {
+		'restrained-sans': {
+			typography: {
+				fontFamily: "'Helvetica Neue', Arial, sans-serif",
+				profile: 'restrained',
+			},
+		},
+		'editorial-reading': {
+			typography: {
+				fontFamily: "Georgia, 'Times New Roman', serif",
+				profile: 'reading',
+			},
+		},
+		'system-reading': {
+			typography: {
+				fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+				profile: 'reading',
+			},
+		},
+		'expressive-sans': {
+			typography: {
+				fontFamily: "'Trebuchet MS', 'Helvetica Neue', Arial, sans-serif",
+				profile: 'statement',
+			},
+		},
+	},
+	rhythm: {
+		balanced: {
+			layout: { contentSpacing: 'normal' },
+			typography: { rhythm: 'normal' },
+		},
+		compact: {
+			layout: { contentSpacing: 'compact' },
+			typography: { rhythm: 'compact' },
+		},
+		expansive: {
+			layout: { contentSpacing: 'spacious' },
+			typography: { rhythm: 'airy' },
+		},
+	},
+	geometry: {
+		'image-led': {
+			layout: {
+				textWidth: 'wide',
+				pageWidth: '1240px',
+				localNavigationGap: 'clamp(1rem, 2vw, 1.75rem)',
+				noteWidth: '13rem',
+				noteGap: '1.5rem',
+				gutter: {
+					desktop: 'clamp(1.25rem, 4vw, 3rem)',
+					mobile: '1rem',
+				},
+			},
+		},
+		'focused-reading': {
+			layout: {
+				textWidth: 'narrow',
+				pageWidth: '1240px',
+				localNavigationGap: 'clamp(1rem, 2vw, 1.5rem)',
+				noteWidth: '12rem',
+				noteGap: '1.25rem',
+				gutter: {
+					desktop: 'clamp(1.25rem, 4vw, 3rem)',
+					mobile: '1rem',
+				},
+			},
+		},
+		'balanced-site': {
+			layout: {
+				textWidth: 'normal',
+				pageWidth: '1120px',
+				localNavigationGap: 'clamp(1rem, 2vw, 1.5rem)',
+				noteWidth: '12rem',
+				noteGap: '1.25rem',
+				gutter: {
+					desktop: 'clamp(1.25rem, 4vw, 3rem)',
+					mobile: '1rem',
+				},
+			},
+		},
+		'expansive-statement': {
+			layout: {
+				textWidth: 'normal',
+				pageWidth: '1280px',
+				localNavigationGap: 'clamp(1rem, 2vw, 1.75rem)',
+				noteWidth: '13rem',
+				noteGap: '1.75rem',
+				gutter: {
+					desktop: 'clamp(1.5rem, 5vw, 4rem)',
+					mobile: '1rem',
+				},
+			},
+		},
+	},
+	media: {
+		prominent: {
+			images: {
+				presentation: 'centered-fit',
+				width: '1000px',
+				maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+				maxAvailableHeightPercent: { desktop: 78, mobile: 68 },
+			},
+		},
+		supporting: {
+			images: {
+				presentation: 'prose-aligned',
+				width: '920px',
+				maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+			},
+		},
+		balanced: {
+			images: {
+				presentation: 'prose-aligned',
+				width: '840px',
+				maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+			},
+		},
+		immersive: {
+			images: {
+				presentation: 'centered-fit',
+				width: '1080px',
+				maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+				maxAvailableHeightPercent: { desktop: 80, mobile: 70 },
+			},
+		},
+	},
+	blocks: {
+		'wide-cards': {
+			blocks: { cardList: { width: 'wide' } },
+		},
+		'reading-column-cards': {
+			blocks: { cardList: { width: 'text' } },
+		},
+		'balanced-cards': {
+			blocks: { cardList: { width: 'normal' } },
+		},
+	},
+	corners: {
+		square: { corners: 'square' },
+		rounded: { corners: 'rounded' },
+	},
+	surfaces: {
+		uniform: { sections: { backgroundPattern: 'uniform' } },
+		alternating: { sections: { backgroundPattern: 'alternating' } },
+		accented: { sections: { backgroundPattern: 'accented' } },
+	},
+});
+
+export const themeProfileCategoryNames = Object.freeze(Object.keys(themeProfileDefinitions));
+
+const collectLeafPaths = (value, prefix = '') => Object.entries(value).flatMap(([key, child]) => {
+	const path = prefix ? `${prefix}.${key}` : key;
+	if (child !== null && typeof child === 'object' && !Array.isArray(child)) {
+		return collectLeafPaths(child, path);
+	}
+
+	return path;
+});
+
+const formatAvailableProfiles = (category) => Object.keys(themeProfileDefinitions[category]).join(', ');
+
+export const resolveThemeProfileRecipe = (recipe, sourceLabel = 'theme preset recipe') => {
+	if (recipe === null || typeof recipe !== 'object' || Array.isArray(recipe)) {
+		throw new Error(`Theme profile recipe must be an object in ${sourceLabel}.`);
+	}
+
+	const unknownCategories = Object.keys(recipe)
+		.filter((category) => !themeProfileCategoryNames.includes(category));
+	if (unknownCategories.length > 0) {
+		throw new Error(`Unknown theme profile category "${unknownCategories[0]}" in ${sourceLabel}.`);
+	}
+
+	const missingCategories = themeProfileCategoryNames
+		.filter((category) => recipe[category] === undefined);
+	if (missingCategories.length > 0) {
+		throw new Error(`Missing theme profile category "${missingCategories[0]}" in ${sourceLabel}.`);
+	}
+
+	const pathOwners = new Map();
+	let resolved = {};
+
+	for (const category of themeProfileCategoryNames) {
+		const profileName = recipe[category];
+		const profile = themeProfileDefinitions[category][profileName];
+		if (!profile) {
+			throw new Error(
+				`Unknown ${category} profile "${profileName}" in ${sourceLabel}. `
+				+ `Use one of: ${formatAvailableProfiles(category)}.`,
+			);
+		}
+
+		for (const path of collectLeafPaths(profile)) {
+			const previousCategory = pathOwners.get(path);
+			if (previousCategory) {
+				throw new Error(
+					`Theme profile categories "${previousCategory}" and "${category}" both own "${path}" in ${sourceLabel}.`,
+				);
+			}
+			pathOwners.set(path, category);
+		}
+
+		resolved = mergeDeep(resolved, profile);
+	}
+
+	return resolved;
+};