scavold 0.2.0-rc.9 → 0.2.0

package/composables/useCover.js

@@ -0,0 +1,128 @@
+import { computed } from "vue";
+import { containerProps } from "./useContainer.js";
+
+/**
+ * File types a cover renders as a video. Anything else is taken for an image.
+ */
+const VIDEO_EXTENSIONS = new Set( [ "mp4", "m4v", "webm", "ogv", "mov" ] );
+
+/**
+ * Props definition for cover container components. Spread into `defineProps`
+ * alongside any component-specific props.
+ */
+export const coverProps = {
+	...containerProps,
+
+	/** URL of the image or video. */
+	dataSrc: { type: String, default: "" },
+
+	/** Variants of an image `src`, provided by the build. */
+	dataSrcSrcset: { type: String, default: "" },
+	dataSrcWebpSrcset: { type: String, default: "" },
+
+	/** Upright dimensions of an image `src`, provided by the build. */
+	dataSrcWidth: { type: String, default: "" },
+	dataSrcHeight: { type: String, default: "" },
+
+	/** Still image of a video, shown until it plays. */
+	dataPoster: { type: String, default: "" },
+
+	/** Variants of the still image, provided by the build. Declared only so they do
+	 * not end up in the markup: a poster takes a single URL. */
+	dataPosterSrcset: { type: String, default: "" },
+	dataPosterWebpSrcset: { type: String, default: "" },
+	dataPosterWidth: { type: String, default: "" },
+	dataPosterHeight: { type: String, default: "" },
+
+	/** Part of the picture kept visible when cropped, as a CSS `object-position`. */
+	dataFocus: { type: String, default: "" },
+
+	/** Alternative text of an image, accessible label of a video. */
+	dataLabel: { type: String, default: "" },
+
+	/** Whether the content on top is meant to be light or dark, see COVER_TONES. */
+	dataTone: { type: String, default: "" },
+};
+
+/**
+ * Tones an author may ask the content on top of a cover to take. The cover only
+ * marks its choice; the theme decides what light or dark content looks like.
+ */
+export const COVER_TONES = [ "light", "dark" ];
+
+/**
+ * Tells whether a URL names a video by its file extension.
+ *
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isVideoUrl( url ) {
+	const match = /\.([a-z0-9]+)(?:[?#].*)?$/i.exec( String( url ?? "" ) );
+
+	return Boolean( match ) && VIDEO_EXTENSIONS.has( match[1].toLowerCase() );
+}
+
+/**
+ * Describes the width an image is drawn at when it covers the whole window,
+ * cropped to its height: the window's width as long as the window is wider than
+ * the image, and the image's own aspect ratio applied to the window's height
+ * otherwise. A phone held upright thus fetches a variant wide enough for the
+ * part of the image that ends up outside the screen.
+ *
+ * Expressed as a media query rather than `max()`, which Safari does not accept in
+ * `sizes`.
+ *
+ * @param {number} width upright width of the source
+ * @param {number} height upright height of the source
+ * @returns {string} value for the `sizes` attribute
+ */
+export function coverSizes( width, height ) {
+	if ( !( width > 0 ) || !( height > 0 ) ) {
+		return "100vw";
+	}
+
+	const ratio = Math.round( width / height * 10000 ) / 100;
+
+	return `(min-aspect-ratio: ${width}/${height}) 100vw, ${ratio}vh`;
+}
+
+/**
+ * Composable for cover container components.
+ *
+ * Parses the props emitted by the markdown-it container renderer for a `:::cover`
+ * block and exposes derived values ready for binding:
+ *
+ *   - `src`        — URL of the image or video
+ *   - `isVideo`    — whether `src` names a video
+ *   - `srcset`     — variants of an image in its original format
+ *   - `webpSrcset` — variants of an image as WebP
+ *   - `sizes`      — `sizes` value for an image covering the window
+ *   - `poster`     — still image of a video, or empty string
+ *   - `focus`      — CSS `object-position` value, or empty string
+ *   - `label`      — alternative text or accessible label, or empty string
+ *   - `tone`       — `"light"` or `"dark"` for the content on top, or empty string
+ *
+ * @param {object} props reactive props from defineProps
+ * @returns {{ src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone }}
+ */
+export function useCover( props ) {
+	const src = computed( () => props.dataSrc ?? "" );
+	const isVideo = computed( () => isVideoUrl( src.value ) );
+
+	const srcset = computed( () => props.dataSrcSrcset ?? "" );
+	const webpSrcset = computed( () => props.dataSrcWebpSrcset ?? "" );
+	const sizes = computed( () => coverSizes( Number( props.dataSrcWidth ), Number( props.dataSrcHeight ) ) );
+
+	const poster = computed( () => props.dataPoster ?? "" );
+	const focus = computed( () => props.dataFocus ?? "" );
+	const label = computed( () => props.dataLabel ?? "" );
+
+	// Anything but a known tone leaves the choice to the theme.
+	const tone = computed( () => {
+		const value = String( props.dataTone ?? "" ).trim().toLowerCase();
+
+		return COVER_TONES.includes( value ) ? value : "";
+	} );
+
+	return { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone };
+}

package/composables/useVideo.js

@@ -14,7 +14,15 @@ export const videoProps = {
 	/** URL of the poster image shown before playback. */
 	dataPoster: { type: String, default: "" },
 
-	/** Play automatically when the page loads. Implies muted. */
+	/** Variants of the poster image, provided by the build. Declared only so they do
+	 * not end up in the markup: a poster takes a single URL. */
+	dataPosterSrcset: { type: String, default: "" },
+	dataPosterWebpSrcset: { type: String, default: "" },
+	dataPosterWidth: { type: String, default: "" },
+	dataPosterHeight: { type: String, default: "" },
+
+	/** Play automatically once the page is up, unless the visitor asks for reduced
+	 * motion. Implies muted. */
 	dataAutoplay: { type: String, default: null },
 
 	/** Loop the video when it ends. */
@@ -23,14 +31,6 @@ export const videoProps = {
 	/** Mute the audio track. */
 	dataMuted: { type: String, default: null },
 
-	/** Render as a background: the video fills the block and the container's
-	 * body content is layered on top of it. */
-	dataOverlay: { type: String, default: null },
-
-	/** Show the native playback controls. Always present in the default player;
-	 * opt-in in overlay mode, where a background video is normally chrome-free. */
-	dataControls: { type: String, default: null },
-
 	/** Hint for preloading: "none", "metadata" (default), or "auto". */
 	dataPreload: { type: String, default: null },
 
@@ -51,14 +51,12 @@ export const videoProps = {
  *   - `loop`     — boolean
  *   - `muted`    — boolean (forced true when autoplay is true)
  *   - `preload`  — "none" | "metadata" | "auto"
- *   - `overlay`  — boolean, render the video as a background behind the slot
- *   - `controls` — boolean, always true in the default player; opt-in in overlay mode
  *
  * Custom video components should call this composable so they share identical
  * attribute resolution without duplicating the logic.
  *
  * @param {object} props  reactive props from defineProps
- * @returns {{ src, poster, autoplay, loop, muted, preload, overlay, controls, ariaLabel }}
+ * @returns {{ src, poster, autoplay, loop, muted, preload, ariaLabel }}
  */
 export function useVideo( props ) {
 	const src = computed( () => props.dataSrc ?? "" );
@@ -75,15 +73,7 @@ export function useVideo( props ) {
 		( PRELOAD_VALUES.has( props.dataPreload ) ? props.dataPreload : "metadata" )
 	);
 
-	const overlay = computed( () => props.dataOverlay != null );
-
-	// The default player always shows controls; a background video is chrome-free
-	// unless the author opts back in with the `controls` flag.
-	const controls = computed( () =>
-		( overlay.value ? props.dataControls != null : true )
-	);
-
 	const ariaLabel = computed( () => props.dataLabel ?? undefined );
 
-	return { src, poster, autoplay, loop, muted, preload, overlay, controls, ariaLabel };
+	return { src, poster, autoplay, loop, muted, preload, ariaLabel };
 }

package/index.d.ts

@@ -37,6 +37,9 @@ export module Scavold {
 
 	interface AugmentedPageData extends PageData {
 		hierarchy: HierarchyNode;
+
+		/** Name of the container the page opens with, e.g. `"cover"`, or null when it opens with anything else. Known before the content renders, so a layout can arrange its own parts around it. */
+		leadingContainer: string | null;
 	}
 
 	interface MenuItem {

package/l10n/de.json

@@ -9,5 +9,9 @@
 		"previous": "Vorherige Seite",
 		"next": "Nächste Seite",
 		"page": "Seite {number}"
+	},
+	"cover": {
+		"play": "Video abspielen",
+		"pause": "Video anhalten"
 	}
 }

package/l10n/en.json

@@ -9,5 +9,9 @@
 		"previous": "Previous page",
 		"next": "Next page",
 		"page": "Page {number}"
+	},
+	"cover": {
+		"play": "Play video",
+		"pause": "Pause video"
 	}
 }

package/lib/config.js

@@ -8,10 +8,11 @@ import { extractFrontmatterMediaSrcs } from "./excerpt.js";
 import { DEFAULT_FEED_LIMIT, collectFeedPages, renderRss } from "./feed.js";
 import { useMedia } from "./media.js";
 import { patchRenderer } from "./markdown.js";
-import { extractContainerMediaSrcs, mediaPropsOf, registerContainers, resolveContainerMap } from "./containers.js";
+import { extractContainerMediaSrcs, leadingContainerOf, mediaPropsOf, registerContainers, resolveContainerMap } from "./containers.js";
 import { buildSectionManifest, writeSectionManifest } from "./sectionManifest.js";
 import { isExternalUrl, servableRedirectTarget } from "./redirectTarget.js";
 import { assertUniquePageKeys } from "./pageKeys.js";
+import { undeclaredMenus } from "./menus.js";
 import {
 	BUILD_REPORT_DIR, BUILD_REPORT_FILE, formatProblems, renderBuildReport, verifyBuild,
 } from "./verifyBuild.js";
@@ -190,6 +191,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 	let declaredImageWidths = null;
 	let declaredExcerptLength = null;
 	let declaredRetiredUrls = [];
+	let declaredMenus = {};
 
 	try {
 		const { readFile } = await import( "node:fs/promises" );
@@ -204,6 +206,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 		declaredImageWidths = cratlyConfig.image_widths ?? null;
 		declaredExcerptLength = cratlyConfig.excerpt_length ?? null;
 		declaredRetiredUrls = cratlyConfig.retired_urls ?? [];
+		declaredMenus = cratlyConfig.menus ?? {};
 	} catch {
 		// file absent or unparseable — proceed with defaults
 	}
@@ -552,13 +555,17 @@ export async function augmentConfig( rawConfig, options = {} ) {
 	// author is still looking at it, and written out at the end of the build for
 	// whoever configures the server. What Scavold produces is data, not server
 	// configuration: cratly does not assume who serves the site.
-	const legacyRedirects = compileLegacyRedirects(
-		await collectFrontmatterOfAllPages( resolvedConfig ),
-		{ rewrites, retired: declaredRetiredUrls },
-	);
+	const frontmatters = await collectFrontmatterOfAllPages( resolvedConfig );
+	const legacyRedirects = compileLegacyRedirects( frontmatters, { rewrites, retired: declaredRetiredUrls } );
 
 	assertLegacyRedirects( legacyRedirects.problems );
 
+	// A page choosing a menu the site does not declare is in a menu no theme renders.
+	// Worth telling, not worth failing over: the page itself is fine.
+	for ( const { page, menu } of undeclaredMenus( frontmatters, declaredMenus ) ) {
+		console.warn( "[scavold] %s chooses menu '%s', which .cratly.config.yaml does not declare", page, menu );
+	}
+
 	/**
 	 * Writes the redirect manifest, unless the site declares no former addresses.
 	 *
@@ -686,7 +693,21 @@ export async function augmentConfig( rawConfig, options = {} ) {
 				url => media.collectImage( url ),
 			);
 
-			return { hierarchy };
+			// A layout renders its own parts — a breadcrumb, say — before the page
+			// content, so whether the page opens with a container has to be known before
+			// that content is rendered. Read from the source rather than the rendered
+			// page, which does not exist yet when the layout needs it.
+			let leadingContainer = null;
+
+			try {
+				leadingContainer = leadingContainerOf(
+					readFileSync( join( sourceFolder( resolvedConfig ), pageData.filePath ), "utf-8" ),
+				);
+			} catch {
+				// a page without a source file of its own, e.g. a generated one
+			}
+
+			return { hierarchy, leadingContainer };
 		},
 		markdown: {
 			config( md ) {
@@ -744,6 +765,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 				registerContainers( md, containerMap, {
 					mediaProps,
 					resolveMedia: url => media.collectAsset( url ),
+					resolveImage: url => media.collectImage( url ),
 				} );
 			},
 		},

package/lib/containers.js

@@ -29,6 +29,7 @@ function defaultContainerMap() {
 	}
 
 	map.video = "ScavoldVideo";
+	map.cover = "ScavoldCover";
 	map.pagelist = "ScavoldPageList";
 
 	return map;
@@ -54,7 +55,7 @@ function resolveTag( name, map ) {
  * @param {string} containerName the original container name from markdown
  * @returns {string}
  */
-function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia } = {} ) {
+function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia, resolveImage } = {}, leading = false ) {
 	if ( token.nesting !== 1 ) {
 		return `</${tag}>\n`;
 	}
@@ -63,13 +64,28 @@ function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia
 
 	// Arguments declared as `media-file` carry a path relative to the media folder, as
 	// the editor writes them. Turn them into the URL the built site serves.
+	//
+	// One naming an image additionally brings its variants and its upright dimensions
+	// as `<key>-srcset`, `<key>-webp-srcset`, `<key>-width` and `<key>-height`, so a
+	// component can render it responsively instead of loading the widest variant.
 	if ( resolveMedia ) {
 		for ( const key of mediaProps[containerName] ?? [] ) {
 			const value = args[key];
 
-			if ( typeof value === "string" ) {
-				args[key] = resolveMedia( value ) ?? value;
+			if ( typeof value !== "string" ) {
+				continue;
 			}
+
+			const image = resolveImage?.( value );
+
+			if ( image ) {
+				args[`${key}-srcset`] = image.srcset;
+				args[`${key}-webp-srcset`] = image.webpSrcset;
+				args[`${key}-width`] = image.width;
+				args[`${key}-height`] = image.height;
+			}
+
+			args[key] = resolveMedia( value ) ?? value;
 		}
 	}
 
@@ -91,6 +107,13 @@ function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia
 
 	attrs.push( `data-container="${containerName}"` );
 
+	// A container opening the page is marked as such, so a theme can tell a cover at
+	// the top of a page from one further down. It is information only; see
+	// leadingContainerOf() for the page-level counterpart.
+	if ( leading ) {
+		attrs.push( 'data-leading=""' );
+	}
+
 	if ( classes ) {
 		attrs.push( `class="${classes}"` );
 	}
@@ -108,13 +131,16 @@ function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia
  * @param {Object<string,string>} containerMap resolved name→component map
  * @param {object} [options]
  * @param {Function} [options.warn] sink for the undeclared-name reports
+ * @param {Object<string,string[]>} [options.mediaProps] container name → names of its media-file props
+ * @param {function(string): (string|null)} [options.resolveMedia] published URL of a media reference
+ * @param {function(string): (object|null)} [options.resolveImage] variant data of an image reference
  */
-export function registerContainers( md, containerMap, { warn = console.warn, mediaProps, resolveMedia } = {} ) {
-	const renderOptions = { mediaProps, resolveMedia };
+export function registerContainers( md, containerMap, { warn = console.warn, mediaProps, resolveMedia, resolveImage } = {} ) {
+	const renderOptions = { mediaProps, resolveMedia, resolveImage };
 
 	for ( const [ name, tag ] of Object.entries( containerMap ) ) {
 		md.use( ContainerPlugin, name, {
-			render: ( tokens, index ) => renderToken( tag, tokens[index], name, renderOptions ),
+			render: ( tokens, index ) => renderToken( tag, tokens[index], name, renderOptions, index === 0 ),
 		} );
 	}
 
@@ -145,11 +171,31 @@ export function registerContainers( md, containerMap, { warn = console.warn, med
 				);
 			}
 
-			return renderToken( resolveTag( name, containerMap ), tokens[index], name, renderOptions );
+			return renderToken( resolveTag( name, containerMap ), tokens[index], name, renderOptions, index === 0 );
 		},
 	} );
 }
 
+/**
+ * Names the container a page opens with, i.e. the one whose fence is the first thing
+ * in the page body, or null when the page opens with anything else. Follows
+ * markdown-it: the front matter does not count, blank lines do not either, and a
+ * fence may be indented by up to three spaces.
+ *
+ * This is the page-level counterpart of the `data-leading` attribute: a layout
+ * renders its own parts before the page content, so it has to know in advance.
+ *
+ * @param {string} source markdown source of one page, front matter included
+ * @returns {string|null}
+ */
+export function leadingContainerOf( source ) {
+	const body = String( source ?? "" ).replace( /^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/, "" );
+	const first = body.split( /\r?\n/ ).find( line => line.trim() !== "" ) ?? "";
+	const match = /^ {0,3}:{3,}\s*(.*)$/.exec( first );
+
+	return match ? containerNameOf( match[1] ) || null : null;
+}
+
 /**
  * Extracts the container name from a container fence's info string, i.e. the first
  * word after the colons. Returns an empty string when it is not a usable name.

package/lib/media.js

@@ -72,7 +72,7 @@ export function toKebabCase( name ) {
  * @param {string} srcPath absolute path to source image
  * @param {string} outDir absolute path to public output folder
  * @param {number[]} widths list of target widths
- * @returns {Promise<{srcset: string, webpSrcset: string, fallbackSrc: string}>}
+ * @returns {Promise<{srcset: string, webpSrcset: string, fallbackSrc: string, width: number, height: number}>}
  */
 async function generateVariants( srcPath, outDir, widths ) {
 	mkdirSync( outDir, { recursive: true } );
@@ -86,6 +86,7 @@ async function generateVariants( srcPath, outDir, widths ) {
 	const image = sharp( srcPath ).autoOrient();
 	const meta = await image.metadata();
 	const sourceWidth = meta.autoOrient?.width ?? meta.width ?? Infinity;
+	const sourceHeight = meta.autoOrient?.height ?? meta.height;
 
 	const targets = widths.filter( w => w <= sourceWidth );
 
@@ -123,6 +124,10 @@ async function generateVariants( srcPath, outDir, widths ) {
 		srcset: srcsetParts.map( ( { width, url } ) => `${url} ${width}w` ).join( ", " ),
 		webpSrcset: webpSrcsetParts.map( ( { width, url } ) => `${url} ${width}w` ).join( ", " ),
 		fallbackSrc: srcsetParts[srcsetParts.length - 1].url,
+		// Upright dimensions of the source. A component cropping the image to a box of
+		// its own needs the aspect ratio to tell how wide the image is drawn.
+		width: sourceWidth,
+		height: sourceHeight,
 	};
 }
 
@@ -253,6 +258,8 @@ export function useMedia( config, options = {} ) {
 			srcset: variants.srcset,
 			webpSrcset: variants.webpSrcset,
 			sizes: defaultSizes,
+			width: variants.width,
+			height: variants.height,
 		} );
 	}
 
@@ -300,7 +307,7 @@ export function useMedia( config, options = {} ) {
 		 *
 		 * @param {string} imageUrl value of the src attribute from markdown
 		 * @param {string} [sizesOverride] per-image sizes attribute override
-		 * @returns {{src: string, srcset: string, webpSrcset: string, sizes: string}|null}
+		 * @returns {{src: string, srcset: string, webpSrcset: string, sizes: string, width: number, height: number}|null}
 		 */
 		collectImage( imageUrl, sizesOverride ) {
 			const data = cache.get( imageUrl );

package/lib/menus.d.ts

@@ -0,0 +1,17 @@
+/** Reserved menu name standing for the menus that follow the page tree. */
+export const AUTO_MENU: "auto";
+
+/** Normalises a page's `menus` front matter into a list of menu names, `auto` when absent. */
+export function menusOf( menus: string | string[] | undefined | null ): string[];
+
+/**
+ * Decides whether a page appears in one menu. A named menu replaces the page tree's
+ * menus rather than adding to it; hiding from menus rules over any choice.
+ */
+export function appearsIn( frontmatter: { [key: string]: any } | undefined, name: string ): boolean;
+
+/** Lists the menu names pages choose that the site does not declare. */
+export function undeclaredMenus(
+	frontmatters: { [page: string]: { [key: string]: any } } | undefined,
+	declared: { [name: string]: unknown } | undefined,
+): Array<{ page: string; menu: string }>;

package/lib/menus.js

@@ -0,0 +1,73 @@
+import { hidesFrom } from "./hide.js";
+
+/**
+ * Reserved menu name standing for the menus that follow the page tree — the ones
+ * `<ScavoldMenu>` renders without a `menu` prop.
+ */
+export const AUTO_MENU = "auto";
+
+/**
+ * Normalises a page's `menus` front matter into a list of menu names.
+ *
+ * Absent or empty means the page tree's menus only, which is how every page behaved
+ * before named menus existed. A single name may be written without a list.
+ *
+ * @param {string|string[]|undefined} menus value of the page's `menus` front matter
+ * @returns {string[]} names of the menus the page is to appear in
+ */
+export function menusOf( menus ) {
+	const names = ( Array.isArray( menus ) ? menus : [menus] )
+		.filter( name => typeof name === "string" && name.trim() )
+		.map( name => name.trim() );
+
+	return names.length ? names : [AUTO_MENU];
+}
+
+/**
+ * Decides whether a page appears in one menu.
+ *
+ * Choosing a named menu replaces the page tree's menus rather than adding to it, so a
+ * page can sit among the folders where it belongs and still be listed elsewhere only.
+ * Hiding a page from menus rules over any choice.
+ *
+ * Shared by the build and the browser, hence its own module, like hide.js.
+ *
+ * @param {object|undefined} frontmatter the page's front matter
+ * @param {string} name menu name, {@link AUTO_MENU} for the page tree's menus
+ * @returns {boolean} true when the page is to be listed in that menu
+ */
+export function appearsIn( frontmatter, name ) {
+	if ( hidesFrom( frontmatter?.hide, "menu" ) ) {
+		return false;
+	}
+
+	return menusOf( frontmatter?.menus ).includes( name );
+}
+
+/**
+ * Lists the menu names pages choose that the site does not declare in its
+ * `.cratly.config.yaml`. Such a page is in a menu no theme renders, which is worth
+ * telling the author, not failing the build over.
+ *
+ * @param {Object<string,object>} frontmatters front matter per page file
+ * @param {object|undefined} declared `menus` block of `.cratly.config.yaml`
+ * @returns {Array<{page: string, menu: string}>} each undeclared name, by page
+ */
+export function undeclaredMenus( frontmatters, declared ) {
+	const known = new Set( [ AUTO_MENU, ...Object.keys( declared ?? {} ) ] );
+	const found = [];
+
+	for ( const [ page, frontmatter ] of Object.entries( frontmatters ?? {} ) ) {
+		if ( frontmatter?.menus == null ) {
+			continue;
+		}
+
+		for ( const menu of menusOf( frontmatter.menus ) ) {
+			if ( !known.has( menu ) ) {
+				found.push( { page, menu } );
+			}
+		}
+	}
+
+	return found;
+}

package/lib/sectionManifest.js

@@ -22,7 +22,8 @@ export const SECTION_MANIFEST_FILE = "sections.json";
  *
  * Keep the `video` props in sync with `videoProps` in
  * composables/useVideo.js — that composable defines the runtime (data-*) props;
- * this object describes the same options in the editor's typed vocabulary.
+ * this object describes the same options in the editor's typed vocabulary. The
+ * same goes for `cover` and `coverProps` in composables/useCover.js.
  */
 export const BUILTIN_SECTIONS = {
 	// The seven sectioning wrappers are generic content containers with no
@@ -40,19 +41,14 @@ export const BUILTIN_SECTIONS = {
 		props: {
 			src: { type: "media-file", label: "Video file", required: true },
 			poster: { type: "media-file", label: "Poster image" },
-			overlay: {
+			autoplay: {
 				type: "boolean",
-				label: "Background mode",
-				hint: "Play the video as a background and lay this container's content on top of it.",
+				label: "Autoplay (muted)",
+				hint: "Not for visitors who asked for reduced motion. For a video across the whole window, use a cover instead.",
+				default: false,
 			},
-			autoplay: { type: "boolean", label: "Autoplay (muted)", default: false },
 			loop: { type: "boolean", label: "Loop" },
 			muted: { type: "boolean", label: "Muted" },
-			controls: {
-				type: "boolean",
-				label: "Show controls",
-				hint: "Always shown for a normal video; in background mode the controls are hidden unless you enable this.",
-			},
 			preload: {
 				type: "enum",
 				label: "Preload",
@@ -67,6 +63,40 @@ export const BUILTIN_SECTIONS = {
 		},
 	},
 
+	cover: {
+		label: "Cover",
+		hint: "An image or a video across the full width and height of the window. Anything written inside the section is laid on top of it.",
+		props: {
+			src: {
+				type: "media-file",
+				label: "Image or video",
+				hint: "A video plays muted in a loop, with a button to pause it.",
+				required: true,
+			},
+			poster: {
+				type: "media-file",
+				label: "Still image",
+				hint: "Only for a video: shown until it plays, and instead of it for visitors who asked for reduced motion.",
+			},
+			focus: {
+				type: "text",
+				label: "Focal point",
+				hint: "Part of the picture that stays visible when the window crops it, e.g. \"center top\" or \"30% 60%\".",
+			},
+			label: {
+				type: "text",
+				label: "Description",
+				hint: "Alternative text of the image, or what the video shows. Leave empty when it is decoration only.",
+			},
+			tone: {
+				type: "enum",
+				label: "Content on top",
+				values: [ "light", "dark" ],
+				hint: "\"light\" over a dark picture, \"dark\" over a bright one. Left unset, the site's design decides.",
+			},
+		},
+	},
+
 	pagelist: {
 		label: "Page list",
 		hint: "Links a configurable number of the site's own pages — the latest posts of a blog, for example. Anything written inside the section is rendered above the list.",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scavold",
-	"version": "0.2.0-rc.9",
+	"version": "0.2.0",
 	"type": "module",
 	"description": "VitePress theme framework — a scaffold for building custom VitePress themes with Vue at the core",
 	"keywords": [