@janga/norna 0.7.10 → 0.7.12

package/scripts/lib/site-content.mjs

@@ -20,9 +20,10 @@ const h2Regex = /^##\s+.*$/gm;
 const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
 const deprecatedInlineStyleReferenceRegex = /\[[^\]\n]+\]\{\.([a-z][a-z0-9-]*)\}/g;
 const frontmatterDelimiterRegex = /^---\s*$/;
+const knownConfigTopLevelFrontmatterKeys = new Set(['url', 'language', 'scrollBehavior']);
 const knownContentTopLevelFrontmatterKeys = new Set(['title', 'description', 'navigation', 'sections']);
-const knownThemeTopLevelFrontmatterKeys = new Set(['navigation', 'layout', 'gallery', 'typography', 'presentation']);
-const knownRouteThemeTopLevelFrontmatterKeys = new Set(['navigation', 'layout', 'gallery', 'typography', 'presentation']);
+const knownThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'gallery', 'typography', 'presentation']);
+const knownRouteThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'gallery', 'typography', 'presentation']);
 const knownSitewideTopLevelFrontmatterKeys = new Set(['navigation', 'banners', 'footer']);
 const knownNestedFrontmatterKeys = new Set([
 	'align',
@@ -270,6 +271,12 @@ export const validateContentFrontmatterStructure = (frontmatter, addIssue) =>
 		fileKind: 'content',
 	});
 
+export const validateConfigFrontmatterStructure = (frontmatter, addIssue) =>
+	validateFrontmatterStructure(frontmatter, addIssue, {
+		knownTopLevelFrontmatterKeys: knownConfigTopLevelFrontmatterKeys,
+		fileKind: 'config',
+	});
+
 export const validateThemeFrontmatterStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownThemeTopLevelFrontmatterKeys,

package/scripts/lib/site-paths.mjs

@@ -22,7 +22,10 @@ export const invocationRoot = configuredInvocationRoot
 
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
-		existsSync(path.join(siteDir, 'config.mjs'))
+		(
+			existsSync(path.join(siteDir, 'config.md'))
+			|| existsSync(path.join(siteDir, 'config.mjs'))
+		)
 		&& existsSync(path.join(siteDir, 'content.md'))
 	);
 };
@@ -114,7 +117,8 @@ const getPathLabel = (filePath) => {
 };
 
 export const siteDir = resolvedSitePaths.siteDir;
-export const siteConfigPath = path.join(siteDir, 'config.mjs');
+export const siteConfigPath = path.join(siteDir, 'config.md');
+export const legacySiteConfigPath = path.join(siteDir, 'config.mjs');
 export const siteThemePath = path.join(siteDir, 'theme.md');
 export const siteContentPath = path.join(siteDir, 'content.md');
 export const sitewideContentPath = path.join(siteDir, 'sitewide-content.md');

package/scripts/lib/theme-config.mjs

@@ -14,6 +14,7 @@ import {
 	siteThemePath,
 	sitewideContentLabel,
 } from './site-paths.mjs';
+import { resolveThemeConfig } from './theme-presets.mjs';
 
 export const readThemeConfig = async () => {
 	const themeFile = await readFile(siteThemePath, 'utf8').catch((error) => {
@@ -40,6 +41,7 @@ export const readThemeConfig = async () => {
 	if (Object.hasOwn(config, 'navigation')) {
 		throw new Error(`${siteThemeLabel} may not define navigation. Brand and logo belong in ${sitewideContentLabel}.`);
 	}
+	resolveThemeConfig(config, siteThemeLabel);
 
 	return config;
 };
@@ -92,6 +94,7 @@ export const validateRouteThemeFiles = async () => {
 		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 });
 	}

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/show-typography.mjs

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { findMap } from './lib/frontmatter-yaml.mjs';
+import { parseYamlMapping } from './lib/frontmatter-yaml.mjs';
 import {
 	defaultTypography,
 	resolveTypographyConfig,
@@ -25,6 +25,7 @@ import {
 	siteThemeLabel,
 	siteThemePath,
 } from './lib/site-paths.mjs';
+import { resolveThemeConfig } from './lib/theme-presets.mjs';
 
 const mode = process.argv[2] ?? 'show';
 
@@ -204,8 +205,8 @@ const readThemeTypography = async () => {
 		].join('\n'));
 	}
 
-	const themeLines = themeFrontmatterBody.split(/\r?\n/);
-	const themeTypographyConfig = findMap(themeLines, 'typography', 0, themeLines.length, 0)?.value;
+	const themeConfig = resolveThemeConfig(parseYamlMapping(themeFrontmatterBody), siteThemeLabel);
+	const themeTypographyConfig = themeConfig.typography;
 	return resolveAnnotatedTypographyConfig(themeTypographyConfig ?? defaultTypography, siteThemeLabel);
 };
 
@@ -231,8 +232,8 @@ const readRouteThemeTypography = async (contentFile, themeTypography) => {
 		].join('\n'));
 	}
 
-	const lines = frontmatterBody.split(/\r?\n/);
-	const typographyConfig = findMap(lines, 'typography', 0, lines.length, 0)?.value;
+	const routeThemeConfig = resolveThemeConfig(parseYamlMapping(frontmatterBody), routeThemeLabel);
+	const typographyConfig = routeThemeConfig.typography;
 	return resolveAnnotatedTypographyConfig(typographyConfig ?? defaultTypography, routeThemeLabel);
 };
 

package/scripts/test-client-javascript.mjs

@@ -0,0 +1,236 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const nornaBin = path.join(repoRoot, 'bin', 'norna.mjs');
+const tempParent = path.join(repoRoot, 'node_modules', '.cache');
+await mkdir(tempParent, { recursive: true });
+const tempRoot = await mkdtemp(path.join(tempParent, 'norna-client-javascript-'));
+const siteDir = path.join(tempRoot, 'site');
+const routeDir = path.join(siteDir, 'routes', '010-details');
+const configPath = path.join(siteDir, 'config.md');
+
+const runBuild = () => {
+	const result = spawnSync(process.execPath, [nornaBin, 'build'], {
+		cwd: tempRoot,
+		encoding: 'utf8',
+		env: {
+			...process.env,
+			NORNA_SITE_DIR: siteDir,
+		},
+	});
+
+	if (result.status !== 0) {
+		throw new Error([
+			`norna build exited with code ${result.status}.`,
+			result.stdout.trim(),
+			result.stderr.trim(),
+		].filter(Boolean).join('\n'));
+	}
+};
+
+const readPage = (pathname = 'index.html') => readFile(path.join(tempRoot, 'dist', pathname), 'utf8');
+const getScripts = (html) => html.match(/<script\b[^>]*>[\s\S]*?<\/script>/gi) ?? [];
+const assertNoClientJavaScript = (html, label) => {
+	assert.deepEqual(getScripts(html), [], `${label} should not require client-side JavaScript.`);
+};
+const assertScrollBehavior = (html, behavior, label) => {
+	assert.match(
+		html,
+		new RegExp(`<html\\b[^>]*style="[^"]*scroll-behavior: ${behavior}(?:;|&quot;|\")`),
+		`${label} should render scroll-behavior: ${behavior}.`,
+	);
+};
+const writeConfig = (scrollBehavior) => writeFile(configPath, `---
+url: https://example.com/
+${scrollBehavior ? `scrollBehavior: ${scrollBehavior}\n` : ''}---
+`);
+const writeSvg = (filePath, color) => writeFile(filePath, [
+	'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 90">',
+	`  <rect width="160" height="90" fill="${color}"/>`,
+	'</svg>',
+	'',
+].join('\n'));
+
+try {
+	await mkdir(path.join(siteDir, 'public'), { recursive: true });
+	await writeConfig();
+	await writeFile(path.join(siteDir, 'theme.md'), `---
+typography:
+  preset: text-forward
+presentation:
+  palette: paper
+---
+`);
+	await writeFile(path.join(siteDir, 'sitewide-content.md'), `---
+navigation:
+  brand: Test site
+---
+`);
+	await writeFile(path.join(siteDir, 'content.md'), `---
+title: Static single page
+description: A single page without interactive features.
+sections:
+  intro: {}
+  more: {}
+---
+## Intro {#intro}
+
+Ordinary Markdown needs no client-side JavaScript.
+
+## More {#more}
+
+Additional sections do not make the page interactive.
+`);
+
+	runBuild();
+	const instantHtml = await readPage();
+	assertNoClientJavaScript(instantHtml, 'The default instant scroll mode');
+	assertScrollBehavior(instantHtml, 'auto', 'The default instant scroll mode');
+	assert.match(instantHtml, /<nav class="page-nav"/);
+	assert.match(instantHtml, /href="#intro"/);
+	assert.match(instantHtml, /href="#more"/);
+
+	await writeConfig('browser-smooth');
+	runBuild();
+	const browserSmoothHtml = await readPage();
+	assertNoClientJavaScript(browserSmoothHtml, 'The browser smooth scroll mode');
+	assertScrollBehavior(browserSmoothHtml, 'smooth', 'The browser smooth scroll mode');
+
+	await writeConfig('norna-smooth');
+	runBuild();
+	const nornaSmoothHtml = await readPage();
+	assert.equal(
+		getScripts(nornaSmoothHtml).length,
+		1,
+		'The Norna smooth scroll mode should load only its scroll implementation.',
+	);
+	assertScrollBehavior(nornaSmoothHtml, 'auto', 'The Norna smooth scroll mode');
+	assert.match(
+		getScripts(nornaSmoothHtml)[0],
+		/nornaScrollActive/,
+		'The Norna smooth scroll mode should emit the Norna scroll implementation.',
+	);
+
+	await writeConfig();
+
+	await mkdir(path.join(routeDir, 'images', 'details'), { recursive: true });
+	await writeSvg(path.join(routeDir, 'images', 'details', 'first.svg'), '#7b8f78');
+	await writeSvg(path.join(routeDir, 'images', 'details', 'second.svg'), '#a7664b');
+	await writeFile(path.join(siteDir, 'content.md'), `---
+title: Static baseline
+description: A page without interactive features.
+sections:
+  intro: {}
+---
+## Intro {#intro}
+
+Ordinary Markdown needs no client-side JavaScript.
+`);
+	await writeFile(path.join(routeDir, 'route-content.md'), `---
+title: Details
+description: Static managed images.
+sections:
+  details: {}
+---
+## Details {#details}
+
+Static image stacks remain static.
+
+\`\`\`norna-image-stack
+- image: first.svg
+  caption: First image.
+- image: second.svg
+  caption: Second image.
+\`\`\`
+
+\`\`\`norna-card-list
+- title: Static card
+  text: Cards do not require client-side behaviour.
+\`\`\`
+`);
+
+	runBuild();
+	assertNoClientJavaScript(await readPage(), 'A plain homepage in a multi-page site');
+	assertNoClientJavaScript(
+		await readPage(path.join('details', 'index.html')),
+		'A page with managed image stacks and cards',
+	);
+
+	await writeFile(path.join(siteDir, 'content.md'), `---
+title: Notes
+description: A page with an enhanced sidenote.
+sections:
+  intro: {}
+---
+## Intro {#intro}
+
+This sentence has additional context.{note-ref}
+
+{note: The note remains readable without JavaScript, while alignment is enhanced when JavaScript runs.}
+`);
+	await writeFile(path.join(routeDir, 'route-content.md'), `---
+title: Carousel
+description: An interactive image carousel.
+sections:
+  details: {}
+---
+## Details {#details}
+
+\`\`\`norna-image-carousel
+- image: first.svg
+  caption: First slide.
+- image: second.svg
+  caption: Second slide.
+\`\`\`
+`);
+
+	runBuild();
+	const noteHtml = await readPage();
+	const carouselHtml = await readPage(path.join('details', 'index.html'));
+	assert.equal(getScripts(noteHtml).length, 1, 'A page with notes should load only the note enhancement.');
+	assert.match(noteHtml, /data-note-id=/);
+	assert.equal(getScripts(carouselHtml).length, 1, 'A carousel page should load only the carousel implementation.');
+	assert.match(carouselHtml, /data-carousel/);
+	assert.match(getScripts(carouselHtml)[0], /\ssrc=/, 'Carousel JavaScript should be emitted as a module asset.');
+
+	await writeFile(path.join(siteDir, 'content.md'), `---
+title: Banner
+description: A page with a dismissible banner.
+sections:
+  intro: {}
+---
+## Intro {#intro}
+
+The only interactive feature is the banner.
+`);
+	await writeFile(path.join(routeDir, 'route-content.md'), `---
+title: Details
+description: A second plain page.
+sections:
+  details: {}
+---
+## Details {#details}
+
+Plain route content.
+`);
+	await writeFile(path.join(siteDir, 'sitewide-content.md'), `---
+banners:
+  - id: test-banner
+    title: Test banner
+    text: This banner can be dismissed.
+---
+`);
+
+	runBuild();
+	const bannerHtml = await readPage();
+	assert.equal(getScripts(bannerHtml).length, 1, 'A dismissible banner should load only its dismissal script.');
+	assert.match(getScripts(bannerHtml)[0], /norna-banner:/);
+
+	console.log('Client JavaScript boundaries test passed.');
+} finally {
+	await rm(tempRoot, { force: true, recursive: true });
+}

package/scripts/test-content-check.mjs

@@ -239,6 +239,109 @@ test('content:check accepts valid inline notes and ignores note syntax in code f
 	});
 });
 
+test('content:check accepts wrapped and explicit multiline inline notes', async () => {
+	await withTempProject({
+		site: `---
+title: Multiline inline notes
+description: Fixture
+---
+## Wrapped {#wrapped}
+This paragraph has a formatter-wrapped note.{note-ref}
+
+{note: This note was wrapped by
+an editor before its closing brace.}
+
+## Explicit {#explicit}
+This paragraph has an explicit multiline note.{note-ref}
+
+{note:
+  This note uses the explicit
+  multiline form.
+}
+`,
+		files: [],
+	}, async (root) => {
+		const result = runContentScript(root, ['--check']);
+		const output = getOutput(result);
+
+		assert.equal(result.status, 0, output);
+		assert.match(output, /Content check passed\./);
+	});
+});
+
+test('content:check reports an unclosed multiline inline note', async () => {
+	await withTempProject({
+		site: `---
+title: Unclosed inline note
+description: Fixture
+---
+## Intro {#intro}
+This paragraph has a note reference.{note-ref}
+
+{note: This note never closes
+and continues to the end of the file.
+`,
+		files: [],
+	}, async (root) => {
+		const result = runContentScript(root, ['--check']);
+		const output = getOutput(result);
+
+		assert.equal(result.status, 1, output);
+		assert.match(output, /The note starting on line \d+ is not closed\./);
+		assert.match(output, /End it with "\}" on its own line or at the end of the note text\./);
+	});
+});
+
+test('content:check rejects nested note syntax before a multiline note is closed', async () => {
+	await withTempProject({
+		site: `---
+title: Nested inline note syntax
+description: Fixture
+---
+## Nested note {#nested-note}
+This paragraph has a note reference.{note-ref}
+
+{note: The first note is still open
+{note: A second note starts here.}
+
+## Nested reference {#nested-reference}
+This paragraph has another note reference.{note-ref}
+
+{note: This note is still open
+and contains {note-ref} before closing.}
+`,
+		files: [],
+	}, async (root) => {
+		const result = runContentScript(root, ['--check']);
+		const output = getOutput(result);
+
+		assert.equal(result.status, 1, output);
+		assert.match(output, /is not closed before another note starts on line \d+\./);
+		assert.match(output, /contains "\{note-ref\}" on line \d+\./);
+	});
+});
+
+test('content:check allows escaped and inline-code note syntax inside notes', async () => {
+	await withTempProject({
+		site: `---
+title: Literal inline note syntax
+description: Fixture
+---
+## Intro {#intro}
+This paragraph has a note reference.{note-ref}
+
+{note: Write \\{note: ... to show escaped text, or use \`{note-ref}\` as inline code.}
+`,
+		files: [],
+	}, async (root) => {
+		const result = runContentScript(root, ['--check']);
+		const output = getOutput(result);
+
+		assert.equal(result.status, 0, output);
+		assert.match(output, /Content check passed\./);
+	});
+});
+
 test('content:check rejects unpaired and repeated inline notes', async () => {
 	await withTempProject({
 		site: `---