scavold 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scavold",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"type": "module",
 	"description": "VitePress theme framework — a scaffold for building custom VitePress themes with Vue at the core",
 	"keywords": [
@@ -45,9 +45,11 @@
 	"files": [
 		"components",
 		"composables",
+		"icons",
 		"l10n",
 		"lib",
 		"scripts",
+		"styles",
 		"index.d.ts",
 		"CHANGELOG.md",
 		"COMPONENTS.md",
@@ -65,6 +67,7 @@
 		"docs:preview": "vitepress preview docs",
 		"test:unit": "bun test --coverage",
 		"test:fixture": "bun scripts/check-fixture.js",
+		"icons": "bun scripts/build-icons.js",
 		"test:unit:dev": "bun test --watch",
 		"lint": "eslint .",
 		"lint:fix": "eslint . --fix",

package/scripts/build-icons.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+// Writes the icons of design/icons.svg — the sheet edited in Affinity — to icons/, one
+// SVG per icon in the form the cratly editor shows unchanged. Run it after exporting
+// the sheet again; a unit test fails while icons/ lags behind it.
+//
+//   bun run icons
+
+import { readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { splitIconSheet } from "../lib/icons.js";
+
+const ROOT = resolve( import.meta.dirname, ".." );
+const OUT = join( ROOT, "icons" );
+
+const icons = splitIconSheet( readFileSync( join( ROOT, "design", "icons.svg" ), "utf-8" ) );
+
+for ( const file of readdirSync( OUT ) ) {
+	if ( file.endsWith( ".svg" ) && !icons.has( file.slice( 0, -4 ) ) ) {
+		rmSync( join( OUT, file ) );
+		console.log( `removed icons/${file}` );
+	}
+}
+
+for ( const [ name, markup ] of icons ) {
+	writeFileSync( join( OUT, `${name}.svg` ), markup );
+	console.log( `wrote icons/${name}.svg` );
+}

package/scripts/check-fixture.js

@@ -115,14 +115,30 @@ function tags( html, tag ) {
 	return html.match( new RegExp( `<${tag}[^>]*>`, "g" ) ) ?? [];
 }
 
+/**
+ * Lists the distinct `sizes` attributes in a piece of markup.
+ *
+ * @param {string} html
+ * @returns {string[]} each as written, e.g. `sizes="100vw"`
+ */
+function sizesOf( html ) {
+	return [...new Set( html.match( /sizes="[^"]*"/g ) ?? [] )];
+}
+
 // ── build ────────────────────────────────────────────────────────────────────
 
 linkSelf();
 await writeMedia();
 
 // Remove everything the build is supposed to produce, so no assertion can pass on a
-// leftover from an earlier run.
-for ( const path of [ DIST, MEDIA_OUT, join( SITE, ".cratly" ), join( SITE, ".vitepress", "cache" ) ] ) {
+// leftover from an earlier run. .cratly/icons/ is the site's own source and stays.
+for ( const path of [
+	DIST,
+	MEDIA_OUT,
+	join( SITE, ".cratly", "sections.json" ),
+	join( SITE, ".cratly", "build-report.json" ),
+	join( SITE, ".vitepress", "cache" ),
+] ) {
 	rmSync( path, { recursive: true, force: true } );
 }
 
@@ -152,13 +168,32 @@ const version = JSON.parse( readFileSync( join( ROOT, "package.json" ), "utf-8"
 expect( manifest.adapter?.version === version, "reports this package's version as the adapter version",
 	`found ${manifest.adapter?.version}, expected ${version}` );
 expect( manifest.sections?.video?.props?.src?.type === "media-file", "declares video.src as a media file" );
-expect( manifest.sections?.pagelist?.props?.sort?.values?.join() === "order,date,date-asc,title",
+expect( manifest.sections?.section?.props?.layout?.label?.de === "Anordnung" &&
+	manifest.sections?.section?.props?.layout?.label?.["*"] === "Layout",
+"brings the texts of its section kinds in English and German" );
+expect( manifest.sections?.card?.docs?.de === "https://scavold.io/de/authors/sections.html#card" &&
+	Boolean( manifest.sections?.card?.hint?.de ),
+"explains its section kinds and links where they are described at length" );
+expect( manifest.sections?.pagelist?.props?.sort?.values?.map( choice => choice.value ).join() === "order,date,date-asc,title",
 	"declares the page list's ordering options" );
 expect( manifest.sections?.video?.props?.overlay === undefined, "offers no background mode for a video; that is a cover's" );
 expect( manifest.sections?.teaser?.props?.background?.type === "media-file",
 	"carries the site's own container with its typed props" );
 expect( manifest.sections?.teaser?.props?.variant?.values?.join() === "plain,boxed",
 	"keeps the enum values of a declared prop" );
+expect( manifest.sections?.teaser?.props?.framed?.icon === "frame" &&
+	manifest.sections?.teaser?.props?.align?.values?.map( choice => choice.icon ).join() === "align-left,align-right",
+"keeps the icons of a boolean prop and of enum choices" );
+expect( /^<svg[^>]*>[\s\S]*<\/svg>$/.test( manifest.icons?.frame ?? "" ) &&
+	/^<svg/.test( manifest.icons?.["align-left"] ?? "" ),
+"embeds the icons it refers to from .cratly/icons/" );
+expect( !( "unused" in ( manifest.icons ?? {} ) ), "leaves out an icon nothing refers to" );
+expect( [ "stacked", "float-left", "float-right", "split-left", "split-right" ].every( n => /^<svg/.test( manifest.icons?.[n] ?? "" ) ) &&
+	manifest.sections?.section?.props?.layout?.values?.length === 4,
+"offers the layout of a section with Scavold's own icons" );
+expect( !( "align-right" in ( manifest.icons ?? {} ) ) &&
+	/icon 'align-right' is used in \.cratly\.config\.yaml, but there is no \.cratly\/icons\/align-right\.svg/.test( log ),
+"reports an icon that is referred to but missing" );
 
 // ── containers ───────────────────────────────────────────────────────────────
 
@@ -177,6 +212,46 @@ expect( !containers.includes( ":::" ), "leaves no container fence unparsed",
 	"a fence survived into the output" );
 expect( /<div class="teaser dark"[^>]*data-background="\/media\/wide--\d+w-[0-9a-f]+\.jpg"/.test( containers ),
 	"resolves a media-file argument of a declared container to its published URL" );
+const details = tags( containers, "details" );
+expect( details.length === 3 && details.every( t => t.includes( 'class="scavold-details' ) ),
+	"renders a details container as a native <details>", `found ${details.length}` );
+expect( details.filter( t => /\sname="faq"/.test( t ) ).length === 2,
+	"names the group of a details block, so the browser closes the others" );
+expect( details.filter( t => /\sopen(=""|\s|>)/.test( t ) ).length === 1,
+	"expands only the details block asking for it" );
+expect( /<summary class="scavold-details__summary">Questions &amp; answers<\/summary>/.test( containers ),
+	"shows the title of a details block, an ampersand included" );
+expect( /<summary class="scavold-details__summary">Details<\/summary>/.test( containers ),
+	"gives a details block without a title a translated one" );
+const grids = tags( containers, "div" ).filter( t => t.includes( "scavold-grid" ) );
+expect( grids.length === 3 &&
+	/class="scavold-grid scavold-grid--3"/.test( grids[0] ) && /--scavold-grid-columns:\s*3/.test( grids[0] ) &&
+	/class="scavold-grid scavold-grid--2"/.test( grids[1] ) && /--scavold-grid-columns:\s*2/.test( grids[1] ),
+"renders a grid with the columns asked for, and two without", grids.join( "\n          " ) );
+const firstGrid = containers.slice( containers.indexOf( "scavold-grid--3" ), containers.indexOf( "scavold-grid--2" ) );
+expect( /<section class="cell"/.test( firstGrid ) && firstGrid.includes( "Fourth cell" ),
+	"keeps an embedded section and the blocks after it inside the grid" );
+expect( /alt="Nested in a cell"/.test( firstGrid ) &&
+	sizesOf( firstGrid.slice( firstGrid.indexOf( "<picture" ), firstGrid.indexOf( "Nested in a cell" ) ) ).join() ===
+		'sizes="(min-width: 40rem) 10rem, 100vw"',
+"hands the grid's image sizes down to an image nested deeper in a cell" );
+const cardGrid = containers.slice( containers.lastIndexOf( "scavold-grid--2" ) );
+expect( sizesOf( cardGrid.slice( 0, cardGrid.indexOf( "Get in touch" ) ) ).join() === 'sizes="(min-width: 40rem) 32rem, 100vw"',
+	"keeps the site's image sizes in a grid whose column count the theme leaves out" );
+const cards = tags( containers, "div" ).filter( t => /class="scavold-card[\s"]/.test( t ) );
+const cardLinks = tags( containers, "a" ).filter( t => t.includes( "scavold-card__link" ) );
+expect( cards.length === 3, "renders each card container as a card", `found ${cards.length}` );
+expect( cards.filter( t => t.includes( "scavold-card--linked" ) ).length === 1 && cardLinks.length === 1,
+	"links only the card naming an existing page", cardLinks.join( "\n          " ) );
+expect( /href="\/contact\.html"/.test( cardLinks[0] ?? "" ) && /aria-label="Read more: Contact"/.test( cardLinks[0] ?? "" ),
+	"names the linked page in the accessible name of a card's link" );
+expect( />Read more<\/a>/.test( containers ), "shows a translated text on a card's link" );
+expect( tags( containers, "section" ).some( t => /data-layout="float-left"/.test( t ) ) &&
+	tags( containers, "aside" ).some( t => /data-layout="split-right"/.test( t ) ),
+"marks a sectioning container with the layout asked for" );
+const css = new Bun.Glob( "assets/**/*.css" ).scanSync( { cwd: DIST } ).map( f => readFileSync( join( DIST, f ), "utf-8" ) ).toArray().join( "\n" );
+expect( /\[data-layout=(["']?)split-left\1\]/.test( css ) && /@container/.test( css ),
+	"ships the stylesheet of the layout variants with the theme" );
 expect( /<div class="not-declared-anywhere"/.test( containers ),
 	"renders an undeclared container through the catch-all" );
 expect( /container ':::not-declared-anywhere' is not declared/.test( log ),
@@ -211,6 +286,29 @@ expect( media.includes( 'sizes="(min-width: 40rem) 32rem, 100vw"' ),
 	"applies the sizes value from the site configuration" );
 expect( media.includes( 'sizes="100vw"' ), "lets a single image override sizes through its title" );
 expect( media.includes( 'src="https://example.com/absent.png"' ), "leaves a remote image untouched" );
+expect( !/title="sizes=/.test( media ), "keeps a sizes override out of the page, where it would show as a tooltip" );
+
+const figures = media.match( /<figure class="scavold-figure"[^>]*>[\s\S]*?<\/figure>/g ) ?? [];
+const caption = text => figures.find( f => new RegExp( `<figcaption class="scavold-figure__caption"[^>]*>${text}</figcaption>` ).test( f ) );
+expect( figures.length === 6, "turns each image standing alone with a caption into a figure", `found ${figures.length}` );
+expect( /<picture[\s\S]*alt="Wide gradient, captioned"/.test( caption( "A gradient &amp; its caption" ) ?? "" ),
+	"puts the image and its caption into the figure, keeping the alt text apart" );
+expect( !figures.some( f => /\stitle="/.test( f ) ), "gives a figure's image no tooltip repeating the caption" );
+expect( /sizes="50vw"/.test( caption( "The narrow one" ) ?? "" ),
+	"reads an override and a caption from the same title" );
+expect( /<p>Amid text, an image <picture title="Inline caption">/.test( media ),
+	"leaves an image amid text in its paragraph, its caption as a tooltip" );
+expect( /<div class="scavold-grid scavold-grid--3"[^>]*>(?:\s|<!--\[-->)*<figure class="scavold-figure"/.test( media ) &&
+	[ "First", "Second", "Third" ].every( n => caption( `${n} of the gallery` ) ),
+"builds a gallery from a grid of captioned images" );
+
+const GRID_SIZES = 'sizes="(min-width: 40rem) 10rem, 100vw"';
+const SITE_SIZES = 'sizes="(min-width: 40rem) 32rem, 100vw"';
+expect( [ "First", "Second", "Third" ].every( n => sizesOf( caption( `${n} of the gallery` ) ?? "" ).join() === GRID_SIZES ),
+	"gives the images of a grid the sizes the theme declares for its column count",
+	sizesOf( caption( "First of the gallery" ) ?? "" ).join() );
+expect( sizesOf( caption( "Fourth of the gallery" ) ?? "" ).join() === 'sizes="50vw"',
+	"keeps an image's own sizes override inside a grid" );
 
 /**
  * Tells which edge of a published variant is red, the colour marking the top.
@@ -352,6 +450,21 @@ expect( menu.includes( '<a href="/containers.html">' ),
 expect( crumbs.includes( '<a href="/blog/index.html"' ) && crumbs.includes( 'aria-current="page"' ),
 	"marks the page the breadcrumb ends on" );
 
+console.log( "\nfolders without an index page" );
+
+const sitemapNav = ( blogPage.match( /<nav aria-label="Sitemap"[\s\S]*?<\/nav>/ ) ?? [""] )[0];
+const guidePage = built( join( "guides", "first.html" ) );
+const guideCrumbs = ( guidePage.match( /<nav class="breadcrumb"[\s\S]*?<\/nav>/ ) ?? [""] )[0];
+
+expect( ![ blogPage, guidePage ].some( page => page.includes( 'href="/guides.html"' ) ),
+	"never links a folder that has no page of its own" );
+expect( !/>guides</.test( menu ),
+	"leaves such a folder out of a menu that shows none of the pages below it" );
+expect( /<span>guides<\/span><ul>(?:<!--\[-->)?<li[^>]*><a href="\/guides\/first\.html"/.test( sitemapNav ),
+	"names such a folder as text above its pages where the menu shows them" );
+expect( /<span>guides<\/span>/.test( guideCrumbs ) && guideCrumbs.includes( 'aria-current="page"' ),
+	"names such a folder as text in the breadcrumb" );
+
 console.log( "\nnamed menus" );
 
 const footer = ( blogPage.match( /<nav aria-label="Footer"[\s\S]*?<\/nav>/ ) ?? [""] )[0];
@@ -413,7 +526,9 @@ expect( entryTitles( dated ).join( " | " ) === "Newest post | Middle post",
 expect( entryTitles( titled ).join( " | " ) === "Middle post | Newest post | Not announced | Oldest post",
 	"orders by title and lists every page when the limit is 0",
 	`found ${entryTitles( titled ).join( " | " ) || "nothing"}` );
-expect( !blog.includes( "Unlisted draft" ), "leaves out a page whose front matter says hide: list" );
+// Menus are left aside: hide: list keeps a page out of lists, not navigation.
+expect( !blog.replace( /<nav[\s\S]*?<\/nav>/g, "" ).includes( "Unlisted draft" ),
+	"leaves out a page whose front matter says hide: list" );
 expect( /<h3 class="scavold-pagelist__title"/.test( dated ) && !/<h\d class="scavold-pagelist__title"/.test( titled ),
 	"uses the requested heading level, and no heading at all without one" );
 // The displayed text follows the page's locale, which the fixture leaves to the

package/styles/layouts.css

@@ -0,0 +1,64 @@
+/*
+ * Layout variants of a section, article or aside — `::: section layout=float-left` —
+ * arranging its first block, an image usually, and the content after it:
+ *
+ *   float-left / float-right   the content flows around the block and on below it
+ *   split-left / split-right   block and content side by side; nothing runs below
+ *
+ * Without a layout, the block stands above the content. Functional only: themes set
+ * the block's width and the gap through the variables, or replace the rules. A section
+ * narrower than 30rem stacks its block above the content again, whatever its layout.
+ */
+
+[data-layout] {
+	--_width: var(--scavold-layout-width, 40%);
+	--_gap: var(--scavold-layout-gap, 1.5rem);
+
+	display: flow-root;
+	container-type: inline-size;
+}
+
+[data-layout] > :first-child img {
+	width: 100%;
+	height: auto;
+}
+
+[data-layout="float-left"] > :first-child,
+[data-layout="split-left"] > :first-child {
+	float: left;
+	width: var(--_width);
+	margin: 0 var(--_gap) var(--_gap) 0;
+}
+
+[data-layout="float-right"] > :first-child,
+[data-layout="split-right"] > :first-child {
+	float: right;
+	width: var(--_width);
+	margin: 0 0 var(--_gap) var(--_gap);
+}
+
+/* Indented by the block's width, the content of a split does not run below it, and
+   the margins between its paragraphs collapse as they would anywhere else. */
+[data-layout="split-left"] > :not(:first-child) {
+	margin-inline-start: calc(var(--_width) + var(--_gap));
+}
+
+[data-layout="split-right"] > :not(:first-child) {
+	margin-inline-end: calc(var(--_width) + var(--_gap));
+}
+
+@container (max-width: 30rem) {
+	[data-layout] > :first-child {
+		float: none;
+		width: auto;
+		margin-inline: 0;
+	}
+
+	[data-layout="split-left"] > :not(:first-child) {
+		margin-inline-start: 0;
+	}
+
+	[data-layout="split-right"] > :not(:first-child) {
+		margin-inline-end: 0;
+	}
+}