scavold 0.2.0-rc.1

package/components/ScavoldMenuItems.vue

@@ -0,0 +1,45 @@
+<script setup lang="ts">
+import type { Scavold } from "../index";
+
+defineProps<{
+	items: Scavold.MenuItem[];
+}>();
+
+function label( node: Scavold.HierarchyNode ): string {
+	if ( node.label ) return node.label;
+	if ( node.title ) return node.title;
+
+	// Fall back to the last meaningful path segment (strip index.md, extension)
+	const segment = node.path
+		.replace( /\/index\.md$/, "" )
+		.replace( /\.md$/, "" )
+		.split( "/" )
+		.filter( Boolean )
+		.pop();
+
+	return segment ?? node.path;
+}
+
+function href( node: Scavold.HierarchyNode ): string {
+	return "/" + ( node.url ?? node.path ).replace( /\.md$/, "" ).replace( /\/index$/, "/" );
+}
+</script>
+
+<template>
+  <ul>
+    <li
+      v-for="item of items"
+      :key="item.node.path"
+      :class="{
+        active: item.active,
+        current: item.current,
+      }"
+    >
+      <a :href="href( item.node )" :aria-current="item.current ? 'page' : undefined">{{ label( item.node ) }}</a>
+      <ScavoldMenuItems
+        v-if="item.children.length"
+        :items="item.children"
+      />
+    </li>
+  </ul>
+</template>

package/components/ScavoldNav.vue

@@ -0,0 +1,12 @@
+<script setup>
+import { useContainer, containerProps } from "../composables/useContainer.js";
+
+const props = defineProps( containerProps );
+const { classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <nav :class="classes" v-bind="dataAttrs">
+    <slot />
+  </nav>
+</template>

package/components/ScavoldSection.vue

@@ -0,0 +1,12 @@
+<script setup>
+import { useContainer, containerProps } from "../composables/useContainer.js";
+
+const props = defineProps( containerProps );
+const { classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <section :class="classes" v-bind="dataAttrs">
+    <slot />
+  </section>
+</template>

package/components/ScavoldSimpleRedirect.vue

@@ -0,0 +1,35 @@
+<script setup>
+import { useData } from "vitepress";
+import { computed, onMounted } from "vue";
+import { isExternalUrl, servableRedirectTarget } from "../lib/redirectTarget.js";
+
+const { frontmatter, page } = useData();
+
+// The resolved, server-servable redirect target.  External URLs pass through
+// unchanged — they are handled at build time via <meta http-equiv="refresh">
+// injected by transformPageData (direct page loads) and by the capture-phase
+// click interceptor in lib/index.js (SPA navigation).  Only internal targets
+// need runtime handling here.
+const target = computed( () => {
+	const redirect = frontmatter.value.redirect;
+	if ( typeof redirect !== "string" ) return null;
+	if ( isExternalUrl( redirect ) ) return null;
+	if ( redirect.startsWith( "/" ) ) return servableRedirectTarget( redirect );
+	// Relative .md path — resolve against the current page's directory.
+	// page.relativePath is used (not location.href) so the computed works in
+	// SSR/build context where location is undefined.
+	const dir = page.value.relativePath.replace( /\/[^/]*$/, "" );
+	const resolved = dir ? `${dir}/${redirect}` : redirect;
+	return servableRedirectTarget( "/" + resolved.replace( /\/index\.md$/, "/" ).replace( /\.md$/, "" ) );
+} );
+
+onMounted( () => {
+	if ( !target.value ) return;
+	// Internal redirects: replace the history entry so this page never appears
+	// in the browser back-stack.  This path is taken on both direct page loads
+	// and (as a fallback) SPA navigations not caught by the click interceptor.
+	location.replace( target.value );
+} );
+</script>
+
+<template><!-- redirect handled in head (external) or onMounted (internal) --></template>

package/components/ScavoldVideo.vue

@@ -0,0 +1,74 @@
+<script setup>
+import { useVideo, videoProps } from "../composables/useVideo.js";
+
+const props = defineProps( videoProps );
+
+const { src, poster, autoplay, loop, muted, preload, overlay, controls, ariaLabel } =
+	useVideo( props );
+</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 -->
+  <video
+    v-else-if="src"
+    class="scavold-video scavold-video__media"
+    :src="src"
+    :poster="poster || undefined"
+    :autoplay="autoplay || undefined"
+    :loop="loop || undefined"
+    :muted="muted || undefined"
+    :preload="preload"
+    :aria-label="ariaLabel"
+    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

@@ -0,0 +1,391 @@
+import { useData } from "vitepress";
+import { computed } from "vue";
+import { useL10n } from "@cepharum/vue3-i18n";
+import type { Scavold } from "../index";
+
+/**
+ *
+ */
+export function useHierarchy() {
+	const { page } = useData();
+
+	const reparent = ( node: Scavold.HierarchyNode ) => {
+		if ( node?.subs ) {
+			for ( const sub of Object.values( node.subs ) ) {
+				Object.defineProperty( sub, "parent", { value: node, writable: true } );
+
+				reparent( sub );
+			}
+		}
+	};
+
+	const hierarchy = computed( () => {
+		// eslint-disable-next-line no-shadow
+		const { hierarchy } = page.value as Scavold.AugmentedPageData;
+
+		reparent( hierarchy );
+
+		return hierarchy;
+	} );
+
+	const findByPath = ( thread: Scavold.HierarchyNode | undefined, searchedPath: string ): Scavold.HierarchyNode | undefined => {
+		if ( !thread ) {
+			return undefined;
+		}
+
+		if ( thread.path === searchedPath ) {
+			return thread;
+		}
+
+		if ( thread.subs ) {
+			for ( const sub of Object.values( thread.subs ) ) {
+				const match = findByPath( sub, searchedPath );
+
+				if ( match != null ) {
+					return match;
+				}
+			}
+		}
+
+		return undefined;
+	};
+
+	const current = computed( () => hierarchy.value ? findByPath( hierarchy.value, page.value.filePath ) : undefined );
+
+	/**
+	 * Returns the ancestor of `node` that is exactly `targetDepth` levels below
+	 * the root, following the path upward from `node`. Returns undefined if
+	 * `node` is not deep enough or `targetDepth` is 0 (root itself has no
+	 * listable parent at depth 0).
+	 */
+	const ancestorAtDepth = ( node: Scavold.HierarchyNode | undefined, targetDepth: number ): Scavold.HierarchyNode | undefined => {
+		if ( node == null ) {
+			return undefined;
+		}
+
+		// Compute depth of this node by walking to root.
+		let depth = 0;
+		let iter: Scavold.HierarchyNode | undefined = node;
+
+		while ( iter?.parent ) {
+			depth++;
+			iter = iter.parent;
+		}
+
+		// targetDepth is the depth of *listed items*, so the parent node to
+		// list from is at targetDepth - 1.
+		const parentDepth = targetDepth - 1;
+
+		if ( depth < parentDepth ) {
+			return undefined;
+		}
+
+		// Walk up from node until we reach parentDepth.
+		iter = node;
+
+		for ( let d = depth; d > parentDepth && iter?.parent; d-- ) {
+			iter = iter.parent;
+		}
+
+		return iter;
+	};
+
+	/**
+	 * Returns true if `node` should be hidden in the given rendering context.
+	 * Reads the `hide` frontmatter property:
+	 *   false / absent  — visible everywhere
+	 *   true            — hidden everywhere
+	 *   "menu"          — hidden in menus only
+	 *   "breadcrumb"    — hidden in breadcrumbs only
+	 */
+	const isHidden = ( node: Scavold.HierarchyNode, context: "menu" | "breadcrumb" ): boolean => {
+		const hide = node.frontmatter?.hide;
+
+		if ( hide === true ) {
+			return true;
+		}
+
+		if ( hide === "menu" || hide === "breadcrumb" ) {
+			return hide === context;
+		}
+
+		return false;
+	};
+
+	/**
+	 * Returns true if `node` is on the path from the root to the current page
+	 * (i.e. is an ancestor of current, or is current itself).
+	 */
+	const isOnActivePath = ( node: Scavold.HierarchyNode ): boolean => {
+		let iter: Scavold.HierarchyNode | undefined = current.value;
+
+		while ( iter ) {
+			if ( iter === node ) {
+				return true;
+			}
+
+			iter = iter.parent;
+		}
+
+		return false;
+	};
+
+	/**
+	 * Collects menu items recursively from a starting node.
+	 *
+	 * @param parent     the node whose direct children form the listed items
+	 * @param remaining  levels left to descend; -1 means unlimited
+	 * @param activeOnly only expand children along the active path
+	 * @param expand     expand all nodes with children regardless of active path
+	 */
+	const collectItems = (
+		parent: Scavold.HierarchyNode | undefined,
+		remaining: number,
+		activeOnly: boolean,
+		expand: boolean,
+	): Scavold.MenuItem[] => {
+		if ( parent?.subs == null ) {
+			return [];
+		}
+
+		return Object.values( parent.subs )
+			.filter( node => !isHidden( node, "menu" ) )
+			.map( node => {
+				const shouldDescend = remaining !== 0 && (
+					expand ||
+					( activeOnly && isOnActivePath( node ) )
+				);
+
+				return {
+					node,
+					active: isOnActivePath( node ),
+					current: node === current.value,
+					children: shouldDescend
+						? collectItems( node, remaining === -1 ? -1 : remaining - 1, activeOnly, expand )
+						: [],
+				};
+			} );
+	};
+
+	/**
+	 * Collects the ancestor chain from root to the current page as a flat array
+	 * of MenuItem objects, suitable for breadcrumb rendering.
+	 *
+	 * @param includeCurrent  include the current page as the last item
+	 * @param includeRoot     include the root node as the first item
+	 */
+	const collectAncestors = (
+		includeCurrent: boolean,
+		includeRoot: boolean,
+	): Scavold.MenuItem[] => {
+		const chain: Scavold.HierarchyNode[] = [];
+		let iter: Scavold.HierarchyNode | undefined = current.value;
+
+		while ( iter ) {
+			chain.unshift( iter );
+			iter = iter.parent;
+		}
+
+		return chain
+			.filter( ( node, index ) => {
+				if ( index === 0 && !includeRoot ) {
+					return false;
+				}
+
+				if ( node === current.value && !includeCurrent ) {
+					return false;
+				}
+
+				if ( isHidden( node, "breadcrumb" ) ) {
+					return false;
+				}
+
+				return true;
+			} )
+			.map( node => ( {
+				node,
+				active: true,
+				current: node === current.value,
+				children: [],
+			} ) );
+	};
+
+	/**
+	 * The resolved locale for the current page. Falls back to the browser locale
+	 * (via @cepharum/vue3-i18n) when no ancestor declares one.
+	 */
+	const currentLocale = computed( () =>
+		current.value?.locale ?? useL10n().locale
+	);
+
+	/**
+	 * Resolves a raw path string to a hierarchy node. Supported placeholders:
+	 *   {locale} — full BCP 47 locale tag (e.g. "de-CH", "en")
+	 *   {lang}   — primary language subtag only (e.g. "de", "en")
+	 * Tries the interpolated path as-is, then with `/index.md`, then with `.md`.
+	 */
+	const resolveByPath = ( rawPath: string ): Scavold.HierarchyNode | undefined => {
+		const locale = currentLocale.value ?? "";
+		const lang = locale.split( "-" )[0];
+		const resolved = rawPath
+			.replace( /\{locale\}/g, locale )
+			.replace( /\{lang\}/g, lang );
+
+		return (
+			findByPath( hierarchy.value, resolved ) ??
+			findByPath( hierarchy.value, resolved.replace( /\/?$/, "/index.md" ) ) ??
+			findByPath( hierarchy.value, resolved.replace( /\/?$/, ".md" ) )
+		);
+	};
+
+	/**
+	 * Converts a hierarchy node path to a root-relative href.
+	 * Prefers node.url (the alias output path) when declared.
+	 */
+	const nodeHref = ( node: Scavold.HierarchyNode ): string =>
+		"/" + ( node.url ?? node.path ).replace( /\.md$/, "" ).replace( /\/index$/, "/" );
+
+	/**
+	 * Walks the full hierarchy depth-first and collects every node, flattened.
+	 */
+	const allNodes = ( root: Scavold.HierarchyNode | undefined ): Scavold.HierarchyNode[] => {
+		const result: Scavold.HierarchyNode[] = [];
+
+		const walk = ( node: Scavold.HierarchyNode | undefined ) => {
+			if ( !node ) {
+				return;
+			}
+
+			result.push( node );
+
+			if ( node.subs ) {
+				for ( const sub of Object.values( node.subs ) ) {
+					walk( sub );
+				}
+			}
+		};
+
+		walk( root );
+
+		return result;
+	};
+
+	/**
+	 * Returns the topmost page node for a given locale — the shallowest isPage
+	 * node in the hierarchy that carries that locale.
+	 */
+	const topmostForLocale = ( locale: string ): Scavold.HierarchyNode | undefined => {
+		let best: Scavold.HierarchyNode | undefined;
+		let bestDepth = Infinity;
+
+		for ( const node of allNodes( hierarchy.value ) ) {
+			if ( !node.isPage || node.locale !== locale ) {
+				continue;
+			}
+
+			let depth = 0;
+			let iter: Scavold.HierarchyNode | undefined = node;
+
+			while ( iter?.parent ) {
+				depth++;
+				iter = iter.parent;
+			}
+
+			if ( depth < bestDepth ) {
+				best = node;
+				bestDepth = depth;
+			}
+		}
+
+		return best;
+	};
+
+	/**
+	 * Collects available locale links for the current page.
+	 *
+	 * @param detection
+	 *   "auto"      — try explicit, then inherited, then global; use first non-empty result.
+	 *   "explicit"  — only locales declared in the current page's own `translations` frontmatter.
+	 *   "inherited" — walks up the ancestor chain and, for each locale, uses the link declared
+	 *                 by the *nearest* ancestor (including the current page itself) that has a
+	 *                 `translations` entry for that locale. This means a section index page can
+	 *                 declare `translations` once and all its descendants without their own
+	 *                 translation link will fall back to the section-level translation — useful
+	 *                 when not every page in one locale has a counterpart in another.
+	 *   "global"    — any locale present anywhere in the hierarchy; link goes to the topmost
+	 *                 page of that locale regardless of any `translations` declarations.
+	 * @param includeCurrent  include the current locale in the result (default false)
+	 */
+	const collectLocaleLinks = (
+		detection: Scavold.LocaleDetection,
+		includeCurrent = false,
+	): Scavold.LocaleLink[] => {
+		if ( detection === "auto" ) {
+			for ( const mode of [ "explicit", "inherited", "global" ] as const ) {
+				const result = collectLocaleLinks( mode, includeCurrent );
+
+				if ( result.length > 0 ) {
+					return result;
+				}
+			}
+
+			return [];
+		}
+		const locale = currentLocale.value;
+		const links = new Map<string, string>(); // locale → href
+
+		if ( detection === "global" ) {
+			// Collect all distinct locales in the hierarchy.
+			for ( const node of allNodes( hierarchy.value ) ) {
+				if ( node.isPage && node.locale && !links.has( node.locale ) ) {
+					const top = topmostForLocale( node.locale );
+
+					if ( top ) {
+						links.set( node.locale, nodeHref( top ) );
+					}
+				}
+			}
+		} else {
+			// Walk up the ancestor chain; for "explicit" stop after current node.
+			let iter: Scavold.HierarchyNode | undefined = current.value;
+
+			while ( iter ) {
+				const translations = iter.frontmatter?.translations as Record<string, string> | undefined;
+
+				if ( translations ) {
+					for ( const [ loc, path ] of Object.entries( translations ) ) {
+						if ( !links.has( loc ) ) {
+							links.set( loc, "/" + String( path ).replace( /\.md$/, "" ).replace( /\/index$/, "/" ) );
+						}
+					}
+				}
+
+				if ( detection === "explicit" ) {
+					break;
+				}
+
+				iter = iter.parent;
+			}
+		}
+
+		return Array.from( links.entries() )
+			.filter( ( [ loc ] ) => includeCurrent || loc !== locale )
+			.map( ( [ loc, href ] ) => ( {
+				locale: loc,
+				href,
+				current: loc === locale,
+			} ) );
+	};
+
+	return {
+		hierarchy,
+		current,
+		currentLocale,
+		ancestorAtDepth,
+		isOnActivePath,
+		collectItems,
+		collectAncestors,
+		collectLocaleLinks,
+		resolveByPath,
+	};
+}

package/composables/useContainer.js

@@ -0,0 +1,59 @@
+import { computed } from "vue";
+import { SECTIONING_ELEMENTS } from "../lib/containers.js";
+
+/**
+ * Shared composable for Scavold container components.
+ *
+ * Consumes the props emitted by the markdown-it container renderer and exposes
+ * derived values ready for binding in templates:
+ *
+ *   - `rootTag`       — the HTML element to use as root (sectioning element if
+ *                       the container name matches one, otherwise "div")
+ *   - `containerName` — the original container name from markdown
+ *   - `classes`       — class string from boolean arguments
+ *   - `dataAttrs`     — object of data-* attribute key/value pairs
+ *
+ * Custom container components should declare the same props and call this
+ * composable to get consistent behaviour without duplicating logic.
+ *
+ * @param {import('vue').ToRefs<{class: string, [key: string]: any}>} props
+ * @returns {{ rootTag, containerName, classes, dataAttrs }}
+ */
+export function useContainer( props ) {
+	const containerName = computed( () => props.dataContainer ?? "" );
+
+	const rootTag = computed( () =>
+		SECTIONING_ELEMENTS.has( containerName.value ) ? containerName.value : "div"
+	);
+
+	const classes = computed( () => props.class ?? "" );
+
+	const dataAttrs = computed( () => {
+		const attrs = {};
+
+		for ( const [ key, value ] of Object.entries( props ) ) {
+			if ( key.startsWith( "data-" ) ) {
+				attrs[key] = value;
+			}
+		}
+
+		return attrs;
+	} );
+
+	return { rootTag, containerName, classes, dataAttrs };
+}
+
+/**
+ * Props definition shared by all Scavold container components. Declare these
+ * via `defineProps( containerProps )` in any custom container component.
+ */
+export const containerProps = {
+	class: {
+		type: String,
+		default: "",
+	},
+	dataContainer: {
+		type: String,
+		default: "",
+	},
+};

package/composables/useI18n.js

@@ -0,0 +1,37 @@
+import { useL10n } from "@cepharum/vue3-i18n";
+
+/**
+ * Registers Scavold's built-in translations into the shared l10n context under
+ * the `@scavold` namespace. All keys are accessed as `@scavold.<key>`.
+ *
+ * Call once from enhanceApp before components mount. The consuming theme's own
+ * setLoader() (the default namespace) runs last per library convention, so any
+ * `@scavold.*` key can be overridden by including it in the theme's translation
+ * files.
+ *
+ * Safe to call multiple times — useL10n() returns the same shared context.
+ */
+export function registerScavoldI18n() {
+	useL10n().setNamespaceLoader( "@scavold", locale =>
+		import( `../l10n/${locale}.json` ).catch( () =>
+			import( "../l10n/en.json" )
+		)
+	);
+}
+
+/**
+ * Composable for use inside Scavold components. Returns a reactive `t()`
+ * helper that looks up keys in the `@scavold` namespace.
+ *
+ *   const { t } = useScavoldI18n();
+ *   t("nav.breadcrumb")  // resolves "@scavold.nav.breadcrumb"
+ *
+ * @returns {{ t: (key: string) => import('vue').ComputedRef<string> }}
+ */
+export function useScavoldI18n() {
+	const l10n = useL10n();
+
+	const t = key => l10n.translate( `@scavold.${key}` );
+
+	return { t };
+}

package/composables/useRedirect.js

@@ -0,0 +1,20 @@
+import { computed } from "vue";
+import { useData } from "vitepress";
+
+/**
+ * Provides redirect-related state derived from the current page's frontmatter.
+ *
+ * @returns {{ isLocaleRedirect: import("vue").ComputedRef<boolean> }}
+ */
+export function useRedirect() {
+	const { frontmatter } = useData();
+
+	const isLocaleRedirect = computed( () => {
+		const r = frontmatter.value.redirect;
+		return r !== null && typeof r === "object" && !Array.isArray( r );
+	} );
+
+	const isSimpleRedirect = computed( () => typeof frontmatter.value.redirect === "string" );
+
+	return { isLocaleRedirect, isSimpleRedirect };
+}