@janga/norna 0.7.18 → 0.7.22

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({ 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) => {
@@ -203,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 { shape, layout, images, typography, palette, sections } = preset;
+	const { colorMode, readerControls, corners, layout, images, blocks, typography, palette, sections } = preset;
 
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
@@ -213,8 +168,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.',
+		'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, spacious.',
@@ -236,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)}`,
@@ -250,10 +220,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,221 @@
+import { freezeDeep, mergeDeep } from './object.mjs';
+
+export const themeProfileDefinitions = freezeDeep({
+	color: {
+		'near-monochrome-dark': {
+			colorMode: { default: 'dark' },
+			palette: 'near-monochrome',
+		},
+		'near-monochrome-adaptive': {
+			colorMode: { default: 'system' },
+			palette: 'near-monochrome',
+		},
+		'warm-paper-adaptive': {
+			colorMode: { 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: {
+				width: '1000px',
+				maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+				maxAvailableHeightPercent: { desktop: 78, mobile: 68 },
+			},
+		},
+		supporting: {
+			images: {
+				width: '920px',
+				maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+				maxAvailableHeightPercent: { desktop: 74, mobile: 68 },
+			},
+		},
+		balanced: {
+			images: {
+				width: '840px',
+				maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
+				maxAvailableHeightPercent: { desktop: 70, mobile: 62 },
+			},
+		},
+		immersive: {
+			images: {
+				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;
+};