scavold 0.2.0-rc.9 → 0.2.0

package/FRONTMATTER.md

@@ -274,6 +274,36 @@ in the hierarchy tree — they are only excluded from rendered navigation.
 
 ---
 
+## `menus`
+
+**Type:** `string | string[]`
+
+Names the menus this page appears in: menus the site declares under
+[`menus`](./docs/reference/config.md#menus) in `.cratly.config.yaml`, plus `auto` for the menus following the
+page tree. Pages then no longer need a folder of their own just to be collected into one
+menu.
+
+| Value | Effect |
+|---|---|
+| absent / empty | Same as `auto` (default) |
+| `auto` | In the menus following the page tree, where the page sits among the folders |
+| `footer` or `[ footer ]` | In the named menu only; the page tree's menus leave the page out |
+| `[ auto, footer ]` | Both |
+
+Choosing a named menu replaces `auto` rather than adding to it. [`hide: menu`](#hide)
+rules over any choice. A name the site does not declare is warned about at build time.
+
+Where a named menu shows up is decided by the theme, rendering it with
+[`<ScavoldMenu menu="…">`](./COMPONENTS.md#scavoldmenu).
+
+```yaml
+---
+menus: [ auto, footer ]
+---
+```
+
+---
+
 ## `aliases`
 
 **Type:** `string | string[]`

package/components/ScavoldCover.vue

@@ -0,0 +1,162 @@
+<script setup>
+import { computed, ref } from "vue";
+import { useAutoplay } from "../composables/useAutoplay.js";
+import { useCover, coverProps } from "../composables/useCover.js";
+import { useScavoldI18n } from "../composables/useI18n.js";
+import ScavoldImage from "./ScavoldImage.vue";
+
+const props = defineProps( coverProps );
+
+const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone } = useCover( props );
+
+const { t } = useScavoldI18n();
+const playLabel = t( "cover.play" );
+const pauseLabel = t( "cover.pause" );
+
+const video = ref( null );
+const playing = ref( false );
+
+const style = computed( () => ( focus.value ? { "--scavold-cover-focus": focus.value } : undefined ) );
+
+// Plays while on screen, not for visitors asking for reduced motion — see useAutoplay.
+useAutoplay( video, () => isVideo.value );
+
+/**
+ * Starts or pauses the video. Moving content lasting longer than five seconds must
+ * be pausable (WCAG 2.2.2), which is why a cover video always carries this button.
+ */
+function toggle() {
+	const element = video.value;
+
+	if ( !element ) {
+		return;
+	}
+
+	if ( element.paused ) {
+		element.play()?.catch( () => {
+			// refused by the browser; the button keeps offering to start it
+		} );
+	} else {
+		element.pause();
+	}
+}
+</script>
+
+<template>
+  <div
+    v-if="src"
+    class="scavold-cover"
+    :class="[ { 'scavold-cover--video': isVideo }, tone && `scavold-cover--${tone}` ]"
+    :style="style"
+  >
+    <video
+      v-if="isVideo"
+      ref="video"
+      class="scavold-cover__media"
+      :src="src"
+      :poster="poster || undefined"
+      :aria-label="label || undefined"
+      :aria-hidden="label ? undefined : 'true'"
+      preload="metadata"
+      muted
+      loop
+      playsinline
+      @play="playing = true"
+      @pause="playing = false"
+    />
+    <ScavoldImage
+      v-else
+      class="scavold-cover__media"
+      :src="src"
+      :srcset="srcset"
+      :webp-srcset="webpSrcset"
+      :sizes="sizes"
+      :alt="label"
+      loading="eager"
+      fetchpriority="high"
+    />
+
+    <div class="scavold-cover__overlay">
+      <slot />
+    </div>
+
+    <button
+      v-if="isVideo"
+      type="button"
+      class="scavold-cover__toggle"
+      :aria-label="playing ? pauseLabel : playLabel"
+      @click="toggle"
+    >
+      <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false">
+        <path v-if="playing" d="M4 2h3v12H4zM9 2h3v12H9z" fill="currentColor" />
+        <path v-else d="M4 2l10 6-10 6z" fill="currentColor" />
+      </svg>
+    </button>
+  </div>
+</template>
+
+<style scoped>
+/*
+ * Functional layout: the cover leaves the column it is written in and spans the
+ * window, at least as high as the window. Media and content share one grid cell,
+ * so content taller than the window grows the cover instead of being cut off.
+ *
+ * The breakout assumes a column centred in the window. Themes adjust the height
+ * through --scavold-cover-height, e.g. to leave room for a fixed header.
+ */
+.scavold-cover {
+	position: relative;
+	display: grid;
+	overflow: hidden;
+	width: 100vw;
+	margin-inline: calc(50% - 50vw);
+	min-height: 100vh;
+	min-height: var(--scavold-cover-height, 100svh);
+}
+
+.scavold-cover__media,
+.scavold-cover__overlay {
+	grid-area: 1 / 1;
+	min-width: 0;
+	min-height: 0;
+}
+
+.scavold-cover__media,
+.scavold-cover__media :deep(img) {
+	display: block;
+	width: 100%;
+	height: 100%;
+	margin: 0;
+	border-radius: 0;
+	object-fit: cover;
+	object-position: var(--scavold-cover-focus, 50% 50%);
+}
+
+.scavold-cover__overlay {
+	position: relative;
+	z-index: 1;
+}
+
+/* A sensible default only — themes restyle it through the class. */
+.scavold-cover__toggle {
+	position: absolute;
+	z-index: 2;
+	inset-block-end: 1rem;
+	inset-inline-end: 1rem;
+	display: grid;
+	place-items: center;
+	width: 2.75rem;
+	height: 2.75rem;
+	padding: 0;
+	border: 0;
+	border-radius: 50%;
+	color: #fff;
+	background: rgb(0 0 0 / 0.55);
+	cursor: pointer;
+}
+
+.scavold-cover__toggle:focus-visible {
+	outline: 2px solid #fff;
+	outline-offset: 2px;
+}
+</style>

package/components/ScavoldImage.vue

@@ -5,6 +5,9 @@ defineProps( {
 	webpSrcset: { type: String, default: "" },
 	sizes: { type: String, default: "100vw" },
 	alt: { type: String, default: "" },
+	// An image above the fold — a cover — is wanted at once, not when it scrolls into view.
+	loading: { type: String, default: "lazy" },
+	fetchpriority: { type: String, default: undefined },
 } );
 </script>
 
@@ -26,7 +29,8 @@ defineProps( {
       :alt="alt"
       :role="alt ? undefined : 'presentation'"
       :sizes="sizes"
-      loading="lazy"
+      :loading="loading"
+      :fetchpriority="fetchpriority"
       decoding="async"
     />
   </picture>

package/components/ScavoldMenu.vue

@@ -6,6 +6,12 @@ import type { Scavold } from "../index";
 
 interface MenuProps {
 
+	/** Renders a named menu declared in `.cratly.config.yaml` instead of the page tree:
+	 * the pages choosing it in their `menus` front matter, wherever they sit. `fromPath`
+	 * and `fromRoot` then narrow the part of the site searched — `"{locale}"` keeps a
+	 * multilingual site's menu to one language — and `from` is ignored. */
+	menu?: string;
+
 	/** Selects the parent node by path, supporting a `{locale}` placeholder that is
 	 * replaced with the current page's locale at runtime. Takes priority over
 	 * `fromRoot` and `from` when set. Examples: `"de/footer"`, `"{locale}/footer"`. */
@@ -36,6 +42,7 @@ interface MenuProps {
 }
 
 const props = withDefaults( defineProps<MenuProps>(), {
+	menu: undefined,
 	fromPath: undefined,
 	fromRoot: undefined,
 	from: 0,
@@ -45,9 +52,21 @@ const props = withDefaults( defineProps<MenuProps>(), {
 	label: undefined,
 } );
 
-const { current, ancestorAtDepth, collectItems, resolveByPath } = useHierarchy();
+const { hierarchy, current, ancestorAtDepth, collectItems, collectMenuItems, resolveByPath } = useHierarchy();
 
 const items = computed<Scavold.MenuItem[]>( () => {
+	if ( props.menu !== undefined ) {
+		let scope: Scavold.HierarchyNode | undefined = hierarchy.value;
+
+		if ( props.fromPath !== undefined ) {
+			scope = resolveByPath( props.fromPath );
+		} else if ( props.fromRoot !== undefined ) {
+			scope = ancestorAtDepth( current.value, props.fromRoot );
+		}
+
+		return collectMenuItems( props.menu, scope, props.depth, props.activeOnly, props.expand );
+	}
+
 	let parent: Scavold.HierarchyNode | undefined;
 
 	if ( props.fromPath !== undefined ) {

package/components/ScavoldVideo.vue

@@ -1,39 +1,26 @@
 <script setup>
+import { ref } from "vue";
+import { useAutoplay } from "../composables/useAutoplay.js";
 import { useVideo, videoProps } from "../composables/useVideo.js";
 
 const props = defineProps( videoProps );
 
-const { src, poster, autoplay, loop, muted, preload, overlay, controls, ariaLabel } =
-	useVideo( props );
+const { src, poster, autoplay, loop, muted, preload, ariaLabel } = useVideo( props );
+
+// Started and paused by script while on screen — see useAutoplay.
+const video = ref( null );
+
+useAutoplay( video, () => autoplay.value );
 </script>
 
 <template>
-  <!-- overlay mode: the video is a background, the slot content sits on top -->
-  <div v-if="overlay && src" class="scavold-video scavold-video--overlay">
-    <video
-      class="scavold-video__media"
-      :src="src"
-      :poster="poster || undefined"
-      :autoplay="autoplay || undefined"
-      :loop="loop || undefined"
-      :muted="muted || undefined"
-      :controls="controls || undefined"
-      :preload="preload"
-      :aria-label="ariaLabel"
-      playsinline
-    />
-    <div class="scavold-video__overlay">
-      <slot />
-    </div>
-  </div>
-
-  <!-- default mode: plain inline player; the slot is fallback content -->
+  <!-- the slot is fallback content, and where <track> elements go -->
   <video
-    v-else-if="src"
-    class="scavold-video scavold-video__media"
+    v-if="src"
+    ref="video"
+    class="scavold-video"
     :src="src"
     :poster="poster || undefined"
-    :autoplay="autoplay || undefined"
     :loop="loop || undefined"
     :muted="muted || undefined"
     :preload="preload"
@@ -41,34 +28,6 @@ const { src, poster, autoplay, loop, muted, preload, overlay, controls, ariaLabe
     controls
     playsinline
   >
-    <!-- <track kind="captions" src="..." srclang="..." label="..." /> -->
     <slot />
   </video>
 </template>
-
-<style scoped>
-/*
- * Functional layout only — visual styling (scrim, colours, alignment, min-height)
- * belongs to the consuming theme. The overlay stacks the video and the content in
- * a single grid cell so the content defines the block's height and the video
- * covers the same area behind it.
- */
-.scavold-video--overlay {
-	position: relative;
-	display: grid;
-	overflow: hidden;
-}
-
-.scavold-video--overlay .scavold-video__media {
-	grid-area: 1 / 1;
-	width: 100%;
-	height: 100%;
-	object-fit: cover;
-}
-
-.scavold-video--overlay .scavold-video__overlay {
-	grid-area: 1 / 1;
-	position: relative;
-	z-index: 1;
-}
-</style>

package/composables/hierarchy.ts

@@ -2,6 +2,7 @@ import { useData } from "vitepress";
 import { computed } from "vue";
 import { useL10n } from "@cepharum/vue3-i18n";
 import { hidesFrom } from "../lib/hide.js";
+import { AUTO_MENU, appearsIn } from "../lib/menus.js";
 import { nodePath, pageHref } from "../lib/href.js";
 import type { Scavold } from "../index";
 
@@ -136,7 +137,7 @@ export function useHierarchy() {
 		}
 
 		return Object.values( parent.subs )
-			.filter( node => !isHidden( node, "menu" ) )
+			.filter( node => appearsIn( node.frontmatter, AUTO_MENU ) )
 			.map( node => {
 				const shouldDescend = remaining !== 0 && (
 					expand ||
@@ -154,6 +155,75 @@ export function useHierarchy() {
 			} );
 	};
 
+	/**
+	 * Collects the items of a named menu: the pages below `scope` choosing that menu in
+	 * their `menus` front matter, in page-tree order, wherever they sit among the folders.
+	 *
+	 * Below each of them, `remaining`, `activeOnly` and `expand` descend into sub-pages as
+	 * collectItems() does. A page choosing the menu along with one of its ancestors is
+	 * listed below that ancestor rather than a second time — unless the menu shows no
+	 * sub-pages at all, which keeps it flat and lists the page beside its ancestor.
+	 *
+	 * @param name       menu name as declared in .cratly.config.yaml
+	 * @param scope      the node whose descendants are searched
+	 * @param remaining  levels to descend below each listed page; -1 means unlimited
+	 * @param activeOnly only expand children along the active path
+	 * @param expand     expand all nodes with children regardless of active path
+	 */
+	const collectMenuItems = (
+		name: string,
+		scope: Scavold.HierarchyNode | undefined,
+		remaining: number,
+		activeOnly: boolean,
+		expand: boolean,
+	): Scavold.MenuItem[] => {
+		const contains = ( items: Scavold.MenuItem[], node: Scavold.HierarchyNode ): boolean =>
+			items.some( item => item.node === node || contains( item.children, node ) );
+
+		const items: Scavold.MenuItem[] = [];
+
+		for ( const node of Object.values( scope?.subs ?? {} ) ) {
+			// Searched even below a page left out of the menu: choosing a menu is
+			// deliberate, and a folder that only groups pages is not a reason to drop it.
+			const listedBelow = collectMenuItems( name, node, remaining, activeOnly, expand );
+
+			if ( !appearsIn( node.frontmatter, name ) ) {
+				items.push( ...listedBelow );
+				continue;
+			}
+
+			const shouldDescend = remaining !== 0 && (
+				expand ||
+				( activeOnly && isOnActivePath( node ) )
+			);
+
+			const children = shouldDescend
+				? collectItems( node, remaining === -1 ? -1 : remaining - 1, activeOnly, expand )
+				: [];
+
+			// A menu showing no sub-pages stays flat: what was chosen below is listed beside
+			// its ancestor rather than dropped, or nested where the theme expects no list.
+			if ( remaining === 0 ) {
+				items.push( {
+					node,
+					active: isOnActivePath( node ),
+					current: node === current.value,
+					children: [],
+				}, ...listedBelow );
+				continue;
+			}
+
+			items.push( {
+				node,
+				active: isOnActivePath( node ),
+				current: node === current.value,
+				children: [ ...children, ...listedBelow.filter( item => !contains( children, item.node ) ) ],
+			} );
+		}
+
+		return items;
+	};
+
 	/**
 	 * Collects the pages below a starting node as a flat array, in hierarchy order.
 	 * Unlike collectItems() this keeps no tree shape — a page list presents its
@@ -431,6 +501,7 @@ export function useHierarchy() {
 		ancestorAtDepth,
 		isOnActivePath,
 		collectItems,
+		collectMenuItems,
 		collectPages,
 		collectAncestors,
 		collectLocaleLinks,

package/composables/useAutoplay.js

@@ -0,0 +1,128 @@
+import { onBeforeUnmount, onMounted } from "vue";
+
+/** Share of an element that has to be on screen before its video starts. */
+export const VISIBLE_SHARE = 0.5;
+
+/** Thresholds the observer reports at, fine enough to catch the share above. */
+const THRESHOLDS = Array.from( { length: 21 }, ( _, i ) => i / 20 );
+
+/**
+ * Decides whether an observed element is on screen far enough to play: half of it,
+ * or — for an element higher than the window, which never gets half of itself on
+ * screen — half of the window.
+ *
+ * @param {{intersectionRect: DOMRectReadOnly, boundingClientRect: DOMRectReadOnly, rootBounds: DOMRectReadOnly|null}} entry
+ * @param {number} [share] required share
+ * @returns {boolean}
+ */
+export function isVisibleEnough( { intersectionRect, boundingClientRect, rootBounds }, share = VISIBLE_SHARE ) {
+	const visible = intersectionRect.height;
+	const needed = share * Math.min( boundingClientRect.height, rootBounds?.height ?? Infinity );
+
+	return visible > 0 && visible >= needed;
+}
+
+/**
+ * Starts and pauses a muted video as it scrolls into and out of view, without
+ * overruling the visitor:
+ *
+ * - a video the visitor paused stays paused, even when scrolled back into view,
+ *   until they start it again;
+ * - a video playing with sound is not paused when scrolled away — someone who turned
+ *   it up is listening.
+ *
+ * @param {HTMLVideoElement} element
+ * @returns {{ setVisible: function(boolean): void, detach: function(): void }}
+ */
+export function autoplayControl( element ) {
+	// What this control itself just asked the element to do, to tell the events it
+	// causes apart from the visitor's.
+	let own = null;
+	let heldByVisitor = false;
+
+	const onPlay = () => {
+		if ( own === "play" ) {
+			own = null;
+		} else {
+			heldByVisitor = false;
+		}
+	};
+
+	const onPause = () => {
+		if ( own === "pause" ) {
+			own = null;
+		} else {
+			heldByVisitor = true;
+		}
+	};
+
+	element.addEventListener( "play", onPlay );
+	element.addEventListener( "pause", onPause );
+
+	return {
+		setVisible( visible ) {
+			if ( visible ) {
+				if ( element.paused && !heldByVisitor ) {
+					own = "play";
+					element.muted = true;
+					element.play()?.catch( () => {
+						// Refused by the browser, e.g. in power saving mode; the visitor
+						// can still start it by hand.
+						own = null;
+					} );
+				}
+			} else if ( !element.paused && element.muted ) {
+				own = "pause";
+				element.pause();
+			}
+		},
+
+		detach() {
+			element.removeEventListener( "play", onPlay );
+			element.removeEventListener( "pause", onPause );
+		},
+	};
+}
+
+/**
+ * Plays a video automatically while it is on screen, for components that offer
+ * autoplay. Nothing happens for visitors who ask for reduced motion: they find the
+ * video paused, with a way to start it.
+ *
+ * Deliberately not done with the `autoplay` attribute, which would start the video
+ * before hydration, regardless of both reduced motion and where it is on the page.
+ *
+ * @param {import("vue").Ref<HTMLVideoElement|null>} videoRef template ref of the video
+ * @param {function(): boolean} enabled whether the video is meant to play by itself
+ */
+export function useAutoplay( videoRef, enabled ) {
+	let control = null;
+	let observer = null;
+
+	onMounted( () => {
+		const element = videoRef.value;
+
+		if ( !element || !enabled() || window.matchMedia?.( "(prefers-reduced-motion: reduce)" ).matches ) {
+			return;
+		}
+
+		control = autoplayControl( element );
+
+		if ( typeof IntersectionObserver === "undefined" ) {
+			control.setVisible( true );
+
+			return;
+		}
+
+		observer = new IntersectionObserver(
+			entries => control.setVisible( isVisibleEnough( entries[entries.length - 1] ) ),
+			{ threshold: THRESHOLDS }
+		);
+		observer.observe( element );
+	} );
+
+	onBeforeUnmount( () => {
+		observer?.disconnect();
+		control?.detach();
+	} );
+}