@janga/norna 0.7.6 → 0.7.8

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/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/README.md

@@ -17,8 +17,10 @@ npm run dev -- --kill
 
 Edit site-wide visual defaults in `site/theme.md`, homepage content and section
 overrides in `site/content.md`, technical settings such as URL and locale
-labels in `site/config.mjs`, source images under
-`site/images/<section-id>/`, and static public files under `site/public/`.
+labels in `site/config.mjs`, source images under `site/images/<section-id>/`,
+and static public files under `site/public/`. The image folder name should
+match the section id in Markdown, for example `## Work {#work}` uses
+`site/images/work/`.
 
 Use `site.basePath: '/'` for a custom domain or root-hosted site. For a GitHub
 Pages project site without a custom domain, set both values:

package/starters/basic/site/content.md

@@ -1,16 +1,6 @@
 ---
 title: Example Site
 description: Minimal norna starter site.
-sections:
-  - id: intro
-    presentation:
-      typography:
-        preset: statement
-  - id: work
-  - id: lorem1
-  - id: lorem2
-  - id: lorem3
-
 ---
 
 ## Intro {#intro}
@@ -19,7 +9,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 managed media blocks in Markdown where the media should appear. Put
+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

@@ -23,7 +23,8 @@ npm run dev -- --kill
 - `site/theme.md`: site-wide visual settings such as brand text, layout
   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.
+  links, install command, example usage, benefits, next steps, managed media
+  blocks, and license.
 - `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.
@@ -40,15 +41,18 @@ GitHub Pages workflow uses `npm ci`.
    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.
-4. Edit `site/config.mjs` for public URL, GitHub repository, footer text, and
+4. Put any local source images in the image folder for the Markdown section
+   that references them, for example `site/images/intro/`.
+5. Edit `site/config.mjs` for public URL, GitHub repository, footer text, and
    deploy workflow name.
-5. Update `package.json` with the site's package name and keep
+6. Update `package.json` with the site's package name and keep
    `package-lock.json` committed.
 
 ## Common Commands
 
 ```sh
 npm run norna:check
+npm run norna:sync
 npm run norna:typography:show
 npm run build
 ```

package/starters/project/site/content.md

@@ -3,15 +3,6 @@ title: Your project
 description: A compact project site starter for an open source developer tool.
 navigation:
   label: Home
-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/010-guide/route-content.md

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