scavold 0.2.0-rc.11 → 0.2.0-rc.12

package/CHANGELOG.md

@@ -9,6 +9,15 @@ changes may occur in any release.
 
 ## [Unreleased]
 
+## [0.2.0-rc.12] — 2026-10-03
+
+### Added
+
+- `:::cover` takes `tone=light` or `tone=dark` for content on top that is meant to be
+  light or dark, depending on the picture. It only marks the cover with
+  `scavold-cover--light` or `scavold-cover--dark`; the colours are the theme's. The
+  editor offers it as a choice.
+
 ## [0.2.0-rc.11] — 2026-10-01
 
 ### Added
@@ -334,7 +343,8 @@ First published release. Version `0.1.0` existed in-tree only.
 - Only images are processed out of `media_folder`; other file types (video, documents)
   are never copied into the build output and have to live in the static folder.
 
-[Unreleased]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.11...main
+[Unreleased]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.12...main
+[0.2.0-rc.12]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.11...v0.2.0-rc.12
 [0.2.0-rc.11]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.10...v0.2.0-rc.11
 [0.2.0-rc.10]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.9...v0.2.0-rc.10
 [0.2.0-rc.9]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.8...v0.2.0-rc.9

package/COMPONENTS.md

@@ -451,12 +451,13 @@ the window, cropped to fit — a cover, or hero, at the top of a page. Written a
 | `poster` | `media-file` | — | Only for a video: still image shown until it plays, and instead of playing for visitors who asked for reduced motion. |
 | `focus` | `string` | `50% 50%` | Part of the picture kept visible when the window crops it, as a CSS `object-position` — `center top`, `30% 60%`. |
 | `label` | `string` | — | Alternative text of an image, accessible label of a video. Left out, the picture is treated as decoration. |
+| `tone` | `"light" \| "dark"` | — | Whether the content on top is meant to be light (over a dark picture) or dark (over a bright one). Only marks the cover with `scavold-cover--light` or `scavold-cover--dark`; what that looks like is the theme's. Left out, or with any other value, the cover carries neither class. |
 
 #### Rendered markup
 
 ```html
-<!-- image -->
-<div class="scavold-cover" style="--scavold-cover-focus: center top">
+<!-- image, tone=light -->
+<div class="scavold-cover scavold-cover--light" style="--scavold-cover-focus: center top">
   <picture class="scavold-cover__media">
     <source type="image/webp" srcset="..." sizes="(min-aspect-ratio: 2400/1350) 100vw, 177.78vh" />
     <source srcset="..." sizes="..." />
@@ -504,6 +505,15 @@ html { overflow-x: clip; }
 The overlay is an empty grid cell over the picture; position its content, add a scrim
 for legibility and restyle `.scavold-cover__toggle` as the design asks.
 
+The `tone` an author picked is the theme's to honour. Scavold sets no colour for it;
+a theme gives each tone the colours of its design, including headings and links its
+prose styles colour on their own:
+
+```css
+.scavold-cover--light .scavold-cover__overlay { color: #fff; }
+.scavold-cover--dark .scavold-cover__overlay { color: #000; }
+```
+
 #### A cover opening the page
 
 Where the theme's own parts go around a cover is the theme's choice; Scavold places
@@ -926,12 +936,13 @@ renders the same picture the way its design asks:
 
 ```js
 const props = defineProps( { ...coverProps } );
-const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label } = useCover( props );
+const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone } = useCover( props );
 ```
 
 `srcset`, `webpSrcset` and `sizes` are filled for an image only; the build provides
-the variants and the dimensions `sizes` is derived from. `isVideoUrl( url )` and
-`coverSizes( width, height )` are exported as well.
+the variants and the dimensions `sizes` is derived from. `tone` is `"light"`, `"dark"`
+or empty, one of `COVER_TONES`. `isVideoUrl( url )` and `coverSizes( width, height )`
+are exported as well.
 
 ---
 

package/components/ScavoldCover.vue

@@ -7,7 +7,7 @@ import ScavoldImage from "./ScavoldImage.vue";
 
 const props = defineProps( coverProps );
 
-const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label } = useCover( props );
+const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone } = useCover( props );
 
 const { t } = useScavoldI18n();
 const playLabel = t( "cover.play" );
@@ -46,7 +46,7 @@ function toggle() {
   <div
     v-if="src"
     class="scavold-cover"
-    :class="{ 'scavold-cover--video': isVideo }"
+    :class="[ { 'scavold-cover--video': isVideo }, tone && `scavold-cover--${tone}` ]"
     :style="style"
   >
     <video

package/composables/useCover.js

@@ -39,8 +39,17 @@ export const coverProps = {
 
 	/** 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.
  *
@@ -91,9 +100,10 @@ export function coverSizes( width, height ) {
  *   - `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 }}
+ * @returns {{ src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone }}
  */
 export function useCover( props ) {
 	const src = computed( () => props.dataSrc ?? "" );
@@ -107,5 +117,12 @@ export function useCover( props ) {
 	const focus = computed( () => props.dataFocus ?? "" );
 	const label = computed( () => props.dataLabel ?? "" );
 
-	return { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label };
+	// 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/lib/sectionManifest.js

@@ -88,6 +88,12 @@ export const BUILTIN_SECTIONS = {
 				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.",
+			},
 		},
 	},
 

package/package.json

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

package/scripts/check-fixture.js

@@ -297,7 +297,7 @@ const covers = cover.split( /<div class="scavold-cover[ "]/ ).slice( 1 );
 const [ coverImage = "", coverVideo = "" ] = covers;
 
 expect( covers.length === 2, "renders both covers of the page", `found ${covers.length}` );
-expect( /<div class="scavold-cover"[^>]*\sdata-leading[\s=>]/.test( cover ) && cover.match( /\sdata-leading[\s=>]/g )?.length === 1,
+expect( /<div class="scavold-cover[ "][^>]*\sdata-leading[\s=>]/.test( cover ) && cover.match( /\sdata-leading[\s=>]/g )?.length === 1,
 	"marks the cover opening the page, and only that one" );
 expect( cover.includes( '<main data-leading-container="cover">' ),
 	"tells the layout before the content renders that the page opens with a cover" );
@@ -321,6 +321,9 @@ expect( /class="scavold-cover__overlay"[^>]*>\s*(?:<!--\[-->)?\s*<h1[^>]*>Over t
 const coverVideoTag = tags( coverVideo, "video" )[0] ?? "";
 
 expect( coverVideo.startsWith( "scavold-cover--video" ), "tells a video cover by its file type" );
+// A mark for the theme to style, nothing more.
+expect( /^scavold-cover--light"/.test( coverImage ), "marks the tone asked for the content on top" );
+expect( !/scavold-cover--(light|dark)/.test( coverVideo ), "marks no tone where none is asked for" );
 expect( !cover.includes( "data-poster-srcset" ), "keeps the variants of a still image out of the markup" );
 expect( /src="\/media\/clip\.mp4"/.test( coverVideoTag ) && /poster="\/media\/wide--\d+w-[0-9a-f]+\.jpg"/.test( coverVideoTag ),
 	"resolves a cover video and its still image to their published URLs" );