@janga/norna 0.7.5 → 0.7.7

package/src/lib/sectionContent.ts

@@ -1,14 +1,51 @@
 import type { CollectionEntry } from 'astro:content';
 import projectConfig from '../../scripts/lib/project-config.mjs';
+import {
+	extractNornaMarkdownBlocks,
+	splitNornaMarkdownBlockMarkers,
+	splitNornaRenderedCodeBlocks,
+} from '../../scripts/lib/norna-markdown-blocks.mjs';
 import { applyBasePathToHtml } from './basePath';
+import type { SitePage } from './sitePages';
 
-type SiteSection = CollectionEntry<'site'>['data']['sections'][number];
+type SiteSectionMetadataMap = CollectionEntry<'site'>['data']['sections'];
+type SiteSectionMetadata = SiteSectionMetadataMap[string];
 type ThemePresentation = CollectionEntry<'theme'>['data']['presentation'];
 type InlineStyles = NonNullable<NonNullable<ThemePresentation>['inlineStyles']>;
+type GalleryImage = {
+	image: string;
+	src: string;
+	alt?: string;
+	caption?: string;
+};
+type CardListItem = {
+	title: string;
+	text?: string;
+	image?: string;
+	src?: string;
+	link?: string;
+	'badge-text'?: string;
+};
+type CardListLayout = 'image-top' | 'image-left' | 'image-right';
+type CardListFlow = 'grid' | 'stack';
+type CardListSize = 's' | 'm' | 'l' | 'xl';
+type CardListWidth = 'text' | 'narrow' | 'normal' | 'wide';
+type SectionContentBlock =
+	| { type: 'html'; html: string }
+	| { type: 'image-stack'; images: GalleryImage[] }
+	| { type: 'image-carousel'; images: GalleryImage[] }
+	| { type: 'card-list'; layout: CardListLayout; flow: CardListFlow; size: CardListSize; width: CardListWidth; cards: CardListItem[] };
+export type ResolvedSection = SiteSectionMetadata & {
+	id: string;
+	title: string;
+	contentBlocks: SectionContentBlock[];
+};
 
 const headingRegex = /<h2\b([^>]*)>([\s\S]*?)<\/h2>/gi;
 const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
 const inlineStyleReferenceRegex = /\[([^\]<]+)\]\{\.([a-z][a-z0-9-]*)\}/g;
+const markdownH2Regex = /^##\s+.*$/gm;
+const imageProvenanceCommentRegex = /<!--\s*norna-image-provenance:[\s\S]*?-->/gi;
 
 const stripTags = (html: string) => html.replace(/<[^>]*>/g, '');
 
@@ -58,18 +95,94 @@ const applyInlineStyles = (html: string, inlineStyles: InlineStyles | undefined)
 		return `<span class="inline-style inline-style-${styleName}" style="--inline-style-color: ${style.color}">${text}</span>`;
 	});
 
+const stripImageProvenanceComments = (html: string) => html.replace(imageProvenanceCommentRegex, '');
+
 const prepareContentHtml = (html: string, inlineStyles: InlineStyles | undefined) =>
-	applyBasePathToHtml(projectConfig.site.basePath, applyInlineStyles(html, inlineStyles));
+	applyBasePathToHtml(
+		projectConfig.site.basePath,
+		stripImageProvenanceComments(applyInlineStyles(html, inlineStyles)),
+	);
+
+const getRawMarkdownSections = (markdown: string) => {
+	const matches = Array.from(markdown.matchAll(markdownH2Regex));
+	const sections = new Map<string, string>();
+
+	for (let index = 0; index < matches.length; index += 1) {
+		const match = matches[index];
+		const heading = match[0] ?? '';
+		const id = heading.match(explicitHeadingIdRegex)?.[1];
+		if (!id) continue;
+
+		const start = match.index ?? 0;
+		const next = matches[index + 1];
+		const end = next?.index ?? markdown.length;
+		sections.set(id, markdown.slice(start, end));
+	}
+
+	return sections;
+};
+
+const getImageSourceKey = (page: SitePage, sectionId: string, image: string) => (
+	page.routeDirectory
+		? `routes/${page.routeDirectory}/images/${sectionId}/${image}`
+		: `images/${sectionId}/${image}`
+);
+
+const resolveContentBlocks = (
+	html: string,
+	rawMarkdown: string,
+	page: SitePage,
+	sectionId: string,
+	inlineStyles: InlineStyles | undefined,
+) => {
+	const rawBlocks = extractNornaMarkdownBlocks(rawMarkdown);
+	const splitBlocks = rawBlocks.length > 0
+		? splitNornaRenderedCodeBlocks(html, rawBlocks)
+		: splitNornaMarkdownBlockMarkers(html);
+
+	return splitBlocks.map((block): SectionContentBlock => {
+		if (block.type === 'html') {
+			return {
+				type: 'html',
+				html: prepareContentHtml(block.html, inlineStyles),
+			};
+		}
+
+		return {
+			type: block.type,
+			...(block.type === 'card-list'
+				? {
+					layout: block.layout,
+					flow: block.flow,
+					size: block.size,
+					width: block.width,
+					cards: block.cards.map((card: CardListItem) => ({
+						...card,
+						...(card.image ? { src: getImageSourceKey(page, sectionId, card.image) } : {}),
+					})),
+				}
+				: {
+					images: block.images.map((image: { image: string; alt?: string; caption?: string }) => ({
+						...image,
+						src: getImageSourceKey(page, sectionId, image.image),
+					})),
+				}),
+		};
+	});
+};
 
 export const getSectionsContent = (
 	html: string,
-	sections: SiteSection[],
+	rawMarkdown: string,
+	sectionMetadata: SiteSectionMetadataMap,
+	page: SitePage,
 	inlineStyles?: InlineStyles,
 ) => {
 	const matches = Array.from(html.matchAll(headingRegex));
-	const contentById = new Map<string, { title: string; contentHtml: string }>();
-	const sectionIds = new Set(sections.map((section) => section.id));
-	const markdownSectionIds: string[] = [];
+	const rawSections = getRawMarkdownSections(rawMarkdown);
+	const metadataIds = new Set(Object.keys(sectionMetadata));
+	const sections: ResolvedSection[] = [];
+	const sectionIds = new Set<string>();
 
 	for (let index = 0; index < matches.length; index += 1) {
 		const match = matches[index];
@@ -84,47 +197,29 @@ export const getSectionsContent = (
 		const title = getHeadingTitle(headingHtml);
 
 		if (!explicitId) {
-			console.warn(`Markdown section is missing an explicit heading id: "${title}". Write for example "## ${title} {#${id}}".`);
+			throw new Error(`Section heading "${title}" is missing an explicit id. Write it as: ## ${title} {#${id}}`);
 		}
 
-		if (contentById.has(id)) {
+		if (sectionIds.has(id)) {
 			throw new Error(`Duplicate Markdown section heading id: ${id}`);
 		}
 
-		contentById.set(id, {
+		sectionIds.add(id);
+		sections.push({
+			...(sectionMetadata[id] ?? {}),
+			id,
 			title,
-			contentHtml: prepareContentHtml(content, inlineStyles),
+			contentBlocks: resolveContentBlocks(content, rawSections.get(id) ?? '', page, id, inlineStyles),
 		});
-		markdownSectionIds.push(id);
 	}
 
-	for (const id of contentById.keys()) {
+	for (const id of metadataIds) {
 		if (!sectionIds.has(id)) {
-			console.warn(`Markdown section exists but is not used in frontmatter: ${id}`);
-		}
-	}
-
-	const orderedMarkdownSectionIds = markdownSectionIds.filter((id) => sectionIds.has(id));
-	const frontmatterSectionIds = sections.map((section) => section.id);
-	const hasOrderMismatch = frontmatterSectionIds.some((id, index) => id !== orderedMarkdownSectionIds[index]);
-
-	if (hasOrderMismatch) {
-		console.warn('Markdown section order differs from frontmatter. Run npm run content:sync to sort Markdown according to frontmatter.');
-	}
-
-	return sections.map((section) => {
-		const content = contentById.get(section.id);
-
-		if (!content) {
 			throw new Error(
-				`Cannot find heading for "${section.id}". Each frontmatter section must have a matching level 2 Markdown heading, for example: ## Heading {#${section.id}}`,
+				`Section metadata "${id}" does not match any Markdown section. Add "## Heading {#${id}}" or remove sections.${id}.`,
 			);
 		}
+	}
 
-		return {
-			...section,
-			title: content.title,
-			contentHtml: content.contentHtml,
-		};
-	});
+	return sections;
 };

package/src/lib/sitePages.ts

@@ -1,4 +1,5 @@
 import type { CollectionEntry } from 'astro:content';
+import { parseRouteDirectory } from '../../scripts/lib/route-model.mjs';
 
 type SiteEntry = CollectionEntry<'site'>;
 
@@ -10,9 +11,10 @@ export type SitePage = {
 		label: string;
 		order: number;
 	};
+	pathSegment: string;
 	pathname: string;
-	routeFolder: string | null;
-	slug: string;
+	routeDirectory: string | null;
+	routeId: string;
 	title: string;
 };
 
@@ -25,21 +27,21 @@ const stripRouteIdPrefix = (id: string) => {
 
 export const isHomePageEntry = (entry: SiteEntry) => stripRouteIdPrefix(entry.id) === null;
 
-const getRouteFolder = (entry: SiteEntry) => isHomePageEntry(entry) ? null : stripRouteIdPrefix(entry.id);
+const getRouteDirectory = (entry: SiteEntry) => isHomePageEntry(entry) ? null : stripRouteIdPrefix(entry.id);
 
-const getPageSlug = (entry: SiteEntry) => {
-	if (isHomePageEntry(entry)) return '';
-
-	const routeFolder = getRouteFolder(entry);
-	return entry.data.slug ?? routeFolder ?? '';
+const getRouteMetadata = (entry: SiteEntry) => {
+	const routeDirectory = getRouteDirectory(entry);
+	return routeDirectory ? parseRouteDirectory(routeDirectory, `route directory ${routeDirectory}`) : null;
 };
 
-const getPagePathname = (slug: string) => slug ? `/${slug}/` : '/';
+const getPagePathname = (pathSegment: string) => pathSegment ? `/${pathSegment}/` : '/';
 
 export const getSitePage = (entry: SiteEntry): SitePage => {
 	const isHome = isHomePageEntry(entry);
-	const routeFolder = getRouteFolder(entry);
-	const slug = getPageSlug(entry);
+	const routeMetadata = getRouteMetadata(entry);
+	const routeDirectory = routeMetadata?.routeDirectory ?? null;
+	const routeId = routeMetadata?.routeId ?? '';
+	const pathSegment = isHome ? '' : routeId;
 	const navigation = entry.data.navigation ?? {};
 
 	return {
@@ -48,11 +50,12 @@ export const getSitePage = (entry: SiteEntry): SitePage => {
 		navigation: {
 			include: navigation.include ?? true,
 			label: navigation.label ?? entry.data.title,
-			order: navigation.order ?? (isHome ? 0 : 100),
+			order: isHome ? 0 : routeMetadata?.routeOrder ?? 100,
 		},
-		pathname: getPagePathname(slug),
-		routeFolder,
-		slug,
+		pathSegment,
+		pathname: getPagePathname(pathSegment),
+		routeDirectory,
+		routeId,
 		title: entry.data.title,
 	};
 };
@@ -60,6 +63,8 @@ export const getSitePage = (entry: SiteEntry): SitePage => {
 export const getSitePages = (entries: SiteEntry[]) => {
 	const pages = entries.map(getSitePage);
 	const pathnames = new Map<string, SitePage>();
+	const routeIds = new Map<string, SitePage>();
+	const routeOrders = new Map<number, SitePage>();
 
 	for (const page of pages) {
 		const existing = pathnames.get(page.pathname);
@@ -68,6 +73,22 @@ export const getSitePages = (entries: SiteEntry[]) => {
 		}
 
 		pathnames.set(page.pathname, page);
+
+		if (page.isHome) continue;
+
+		const existingRouteId = routeIds.get(page.routeId);
+		if (existingRouteId) {
+			throw new Error(`Duplicate route id "${page.routeId}" from "${existingRouteId.entry.id}" and "${page.entry.id}".`);
+		}
+
+		routeIds.set(page.routeId, page);
+
+		const existingRouteOrder = routeOrders.get(page.navigation.order);
+		if (existingRouteOrder) {
+			throw new Error(`Duplicate route order "${String(page.navigation.order).padStart(3, '0')}" from "${existingRouteOrder.entry.id}" and "${page.entry.id}".`);
+		}
+
+		routeOrders.set(page.navigation.order, page);
 	}
 
 	return pages.sort((left, right) => (

package/src/pages/[slug].astro

@@ -10,7 +10,7 @@ export async function getStaticPaths() {
 	return pages
 		.filter((page) => !page.isHome)
 		.map((page) => ({
-			params: { slug: page.slug },
+			params: { slug: page.pathSegment },
 			props: { entry: page.entry },
 		}));
 }
@@ -23,8 +23,8 @@ if (!entry || isHomePageEntry(entry)) {
 
 const currentPage = getSitePage(entry);
 
-if (!currentPage.slug) {
-	throw new Error(`Route "${entry.id}" needs a slug or route folder name.`);
+if (!currentPage.pathSegment) {
+	throw new Error(`Route "${entry.id}" needs a route id.`);
 }
 ---
 

package/src/styles/global.css

@@ -458,6 +458,182 @@ ul {
 	margin-top: 0.35rem;
 }
 
+.card-list {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(min(100%, 15rem), 1fr));
+	gap: var(--card-list-gap, clamp(0.9rem, 2vw, 1.25rem));
+	width: min(100%, var(--card-list-width, var(--gallery-layout-width)));
+	margin: 0 auto var(--space-section-body-to-gallery);
+	text-align: left;
+	--card-list-width: var(--gallery-layout-width);
+	--card-list-gap: clamp(0.9rem, 2vw, 1.25rem);
+	--card-list-item-gap: 0.85rem;
+	--card-list-padding: clamp(0.9rem, 2vw, 1.15rem);
+	--card-list-media-width: 32%;
+	--card-list-media-min-width: 7rem;
+	--card-list-top-media-width: 20rem;
+	--card-list-title-scale: 1;
+	--card-list-text-scale: 1;
+}
+
+.card-list-width-text {
+	--card-list-width: var(--text-width);
+}
+
+.card-list-width-narrow {
+	--card-list-width: min(48rem, var(--gallery-layout-width));
+}
+
+.card-list-width-wide {
+	--card-list-width: var(--page-width);
+}
+
+.card-list-size-s {
+	--card-list-gap: 0.75rem;
+	--card-list-item-gap: 0.65rem;
+	--card-list-padding: 0.8rem;
+	--card-list-media-width: 26%;
+	--card-list-media-min-width: 5.5rem;
+	--card-list-top-media-width: 14rem;
+	--card-list-title-scale: 0.92;
+	--card-list-text-scale: 0.92;
+}
+
+.card-list-size-l {
+	--card-list-gap: clamp(1rem, 2.4vw, 1.5rem);
+	--card-list-item-gap: 1rem;
+	--card-list-padding: clamp(1.1rem, 2.4vw, 1.45rem);
+	--card-list-media-width: 36%;
+	--card-list-media-min-width: 8.5rem;
+	--card-list-top-media-width: 24rem;
+	--card-list-title-scale: 1.08;
+	--card-list-text-scale: 1.02;
+}
+
+.card-list-size-xl {
+	--card-list-gap: clamp(1.15rem, 2.8vw, 1.8rem);
+	--card-list-item-gap: 1.1rem;
+	--card-list-padding: clamp(1.25rem, 3vw, 1.75rem);
+	--card-list-media-width: 40%;
+	--card-list-media-min-width: 10rem;
+	--card-list-top-media-width: 28rem;
+	--card-list-title-scale: 1.18;
+	--card-list-text-scale: 1.06;
+}
+
+.card-list-flow-stack {
+	grid-template-columns: 1fr;
+}
+
+.card-list-item {
+	display: grid;
+	gap: var(--card-list-item-gap);
+	align-content: start;
+	margin: 0;
+	border: 1px solid color-mix(in srgb, currentColor 18%, transparent);
+	border-radius: 8px;
+	padding: var(--card-list-padding);
+	background: color-mix(in srgb, var(--section-background-color, var(--color-page)) 92%, currentColor 8%);
+	color: inherit;
+}
+
+.card-list-layout-image-left .card-list-item-has-image,
+.card-list-layout-image-right .card-list-item-has-image {
+	grid-template-columns: minmax(var(--card-list-media-min-width), var(--card-list-media-width)) minmax(0, 1fr);
+	align-items: center;
+}
+
+.card-list-layout-image-right .card-list-item-has-image {
+	grid-template-columns: minmax(0, 1fr) minmax(var(--card-list-media-min-width), var(--card-list-media-width));
+}
+
+.card-list-layout-image-left .card-list-item-linked,
+.card-list-layout-image-right .card-list-item-linked {
+	grid-template-columns: 1fr;
+}
+
+.card-list-layout-image-right .card-list-image-frame {
+	order: 2;
+}
+
+.card-list-link {
+	display: grid;
+	gap: var(--card-list-item-gap);
+	width: 100%;
+	color: inherit;
+	text-decoration: none;
+}
+
+.card-list-layout-image-left .card-list-item-has-image .card-list-link,
+.card-list-layout-image-right .card-list-item-has-image .card-list-link {
+	grid-template-columns: minmax(var(--card-list-media-min-width), var(--card-list-media-width)) minmax(0, 1fr);
+	align-items: center;
+}
+
+.card-list-layout-image-right .card-list-item-has-image .card-list-link {
+	grid-template-columns: minmax(0, 1fr) minmax(var(--card-list-media-min-width), var(--card-list-media-width));
+}
+
+.card-list-link:hover .card-list-title,
+.card-list-link:focus-visible .card-list-title {
+	text-decoration: underline;
+	text-underline-offset: 0.18em;
+}
+
+.card-list-image-frame {
+	display: grid;
+	width: 100%;
+	aspect-ratio: 16 / 10;
+	place-items: center;
+	overflow: hidden;
+}
+
+.card-list-flow-stack.card-list-layout-image-top .card-list-image-frame {
+	width: min(100%, var(--card-list-top-media-width));
+}
+
+.card-list-image {
+	display: block;
+	width: 100%;
+	height: 100%;
+	object-fit: contain;
+}
+
+.card-list-content {
+	display: grid;
+	gap: 0.4rem;
+}
+
+.card-list-badge {
+	justify-self: start;
+	margin: 0 0 0.15rem;
+	border: 1px solid color-mix(in srgb, currentColor 28%, transparent);
+	border-radius: 999px;
+	padding: 0.18rem 0.48rem;
+	background: color-mix(in srgb, currentColor 9%, transparent);
+	color: inherit;
+	font-size: calc(var(--section-body-font-size-desktop, 1rem) * 0.72);
+	font-weight: 700;
+	letter-spacing: 0;
+	line-height: 1.2;
+}
+
+.card-list-title {
+	margin: 0;
+	color: inherit;
+	font-size: calc(var(--section-markdown-h3-font-size-desktop, 1.1rem) * var(--card-list-title-scale));
+	font-weight: 700;
+	letter-spacing: 0;
+	line-height: var(--section-markdown-h3-line-height, 1.35);
+	text-transform: none;
+}
+
+.card-list-content p:not(.card-list-badge) {
+	margin: 0;
+	font-size: calc(var(--section-body-font-size-desktop, 1rem) * var(--card-list-text-scale));
+	line-height: var(--section-body-line-height, 1.5);
+}
+
 .gallery {
 	display: grid;
 	gap: var(--space-gallery-item);
@@ -858,6 +1034,17 @@ ul {
 		text-align: var(--section-markdown-h4-align-mobile, var(--section-markdown-h4-align-desktop, left));
 	}
 
+	.card-list-layout-image-left .card-list-item-has-image,
+	.card-list-layout-image-right .card-list-item-has-image,
+	.card-list-layout-image-left .card-list-item-has-image .card-list-link,
+	.card-list-layout-image-right .card-list-item-has-image .card-list-link {
+		grid-template-columns: 1fr;
+	}
+
+	.card-list-layout-image-right .card-list-image-frame {
+		order: 0;
+	}
+
 	.section-markdown ul,
 	.section-markdown ol {
 		display: block;

package/starters/basic/site/content.md

@@ -2,14 +2,10 @@
 title: Example Site
 description: Minimal norna starter site.
 sections:
-  - id: intro
+  intro:
     presentation:
       typography:
         preset: statement
-  - id: work
-  - id: lorem1
-  - id: lorem2
-  - id: lorem3
 
 ---
 
@@ -19,7 +15,15 @@ routes defined, the navigation menu will be a sticky bar with anchor links for
 ease of use on phones etc. [Highlighted inline text]{.highlight} when a short
 phrase needs emphasis
 ## Work {#work}
-Add image rows in frontmatter and matching source images under images/work/.
+Add Norna image blocks in Markdown and matching source images under
+`images/work/`.
+
+````
+```norna-image-stack
+- image: example.jpg
+  caption: Replace this with a real image and caption.
+```
+````
 ## What is Lorem Ipsum? {#lorem1}
 Lorem Ipsum is simply dummy text of the printing and typesetting
 industry. Lorem Ipsum has been the industry's standard dummy text ever

package/starters/project/README.md

@@ -24,7 +24,7 @@ npm run dev -- --kill
   density, typography rhythm, colors, frame colors, and inline text styles.
 - `site/content.md`: homepage title, sections, placeholders, project summary,
   links, install command, example usage, benefits, next steps, and license.
-- `site/routes/guide/route-content.md`: short secondary page with realistic
+- `site/routes/010-guide/route-content.md`: short secondary page with realistic
   project guide content.
 - `site/public/robots.txt`: static public file copied into the built site.
 
@@ -36,7 +36,7 @@ GitHub Pages workflow uses `npm ci`.
 
 1. Replace the project name, tagline, links, install command, example usage,
    benefits, use cases, and license in `site/content.md`.
-2. Replace the guide examples in `site/routes/guide/route-content.md`, or
+2. Replace the guide examples in `site/routes/010-guide/route-content.md`, or
    delete the route if the homepage is enough.
 3. Edit `site/theme.md` for brand name, layout density, typography rhythm,
    colors, frame colors, and inline text styles.

package/starters/project/site/content.md

@@ -3,16 +3,6 @@ title: Your project
 description: A compact project site starter for an open source developer tool.
 navigation:
   label: Home
-  order: 0
-sections:
-  - id: intro
-  - id: links
-  - id: install
-  - id: example
-  - id: why
-  - id: good-fit
-  - id: next
-  - id: license
 ---
 
 ## `<Your project> - <short value proposition>` {#intro}

package/starters/project/site/routes/{guide → 010-guide}/route-content.md

@@ -3,12 +3,6 @@ title: Guide
 description: Adapt this compact guide for normal project use.
 navigation:
   label: Guide
-  order: 10
-sections:
-  - id: quickstart
-  - id: configuration
-  - id: usage
-  - id: topic
 ---
 
 ## Quickstart {#quickstart}