caracms 0.1.0 → 0.3.0

package/skills/caracms-adopt/look-same.mjs

@@ -27,6 +27,11 @@
 //   --ignore-attr <list> optional: attributes the HTML diff drops, a comma list of names. A name
 //                       ending in * matches by prefix. A Tina port, for example:
 //                       --ignore-attr data-tina-field,data-tina-island  or  --ignore-attr 'data-tina-*'
+//   --css <rules>       optional: CSS added to both pages just before each shot, for an element
+//                       that varies from run to run on the old site itself (a wordmark fitted to its
+//                       box while the display font loads). Hide it or pin its size on both sides, e.g.
+//                       --css '[data-wordmark]{visibility:hidden!important}'. It changes the shots
+//                       only, not the HTML diff.
 //   --mask-ids <regex|auto> optional: ids drawn at random per render (MEC's st-a8f3k2, React's
 //                       :r1:) differ on every build, and so does every attribute that points at
 //                       them. Ids whose value matches the regex (JavaScript syntax, unanchored:
@@ -105,7 +110,7 @@
 // Exit codes: 0 when the report is written (whatever the scores, statuses or image caps), 1 for
 // a usage error, 2 when the report is written but some page couldn't be fetched at all.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -118,7 +123,7 @@ const TOLERANCE = 16;
 function usage(message) {
 	if (message) console.error(`look-same: ${message}`);
 	console.error(
-		'usage: node look-same.mjs --playwright <dir> --old <url> --new <url> --pages <file|a,b,c> --out <dir> [--widths 1440,390] [--image-wait 5] [--ignore-attr a,data-b-*] [--mask-ids <regex>|auto]',
+		'usage: node look-same.mjs --playwright <dir> --old <url> --new <url> --pages <file|a,b,c> --out <dir> [--widths 1440,390] [--image-wait 5] [--ignore-attr a,data-b-*] [--mask-ids <regex>|auto] [--css <rules>]',
 	);
 	process.exit(1);
 }
@@ -137,7 +142,9 @@ function parseArgs(argv) {
 }
 
 function readPages(spec) {
-	const lines = existsSync(spec) ? readFileSync(spec, 'utf8').split('\n') : spec.split(',');
+	// A list file only when it's a file: `--pages /` is the home page, not the disk's root.
+	const isFile = existsSync(spec) && statSync(spec).isFile();
+	const lines = isFile ? readFileSync(spec, 'utf8').split('\n') : spec.split(',');
 	return lines
 		.map((line) => line.replace(/#.*/, '').trim())
 		.filter(Boolean)
@@ -310,7 +317,7 @@ function compare(oldPng, newPng) {
 
 // ---------------------------------------------------------------- taking a page
 
-async function shoot(browser, url, width, imageWaitMs) {
+async function shoot(browser, url, width, imageWaitMs, css) {
 	const context = await browser.newContext({
 		viewport: { width, height: width >= 768 ? 900 : 844 },
 		deviceScaleFactor: 1,
@@ -332,11 +339,13 @@ async function shoot(browser, url, width, imageWaitMs) {
 				const bottom = document.documentElement.scrollHeight - window.innerHeight;
 				if (y >= bottom) break;
 				y = Math.min(y + Math.round(window.innerHeight * 0.75), bottom);
-				window.scrollTo(0, y);
+				// Instant, whatever the page's own `scroll-behavior`: a smooth scroll still moving at
+				// the shot puts a sticky header somewhere else each run (Urban Return port).
+				window.scrollTo({ top: y, behavior: 'instant' });
 				await pause(120);
 			}
 			await pause(300);
-			window.scrollTo(0, 0);
+			window.scrollTo({ top: 0, behavior: 'instant' });
 		});
 		await page.waitForLoadState('networkidle', { timeout: 30_000 }).catch(() => {});
 		await page.evaluate(() => document.fonts.ready);
@@ -371,6 +380,7 @@ async function shoot(browser, url, width, imageWaitMs) {
 			return { stillLoading: still.length, images: still.slice(0, 3).map((img) => img.currentSrc || img.src) };
 		}, imageWaitMs);
 		await page.waitForTimeout(300);
+		if (css) await page.addStyleTag({ content: css });
 		const png = await page.screenshot({ fullPage: true, animations: 'disabled', type: 'png' });
 		return { png, status, imageCap };
 	} finally {
@@ -815,7 +825,9 @@ function renderPage(report, rows) {
 			? ` Ids matching <code>${escape(report.options.maskIds)}</code> (<code>--mask-ids</code>), and the references to them, are written <code>[id1]</code>, <code>[id2]</code>, … in the order the ids come on the page (a reference to an id the page doesn't have is <code>[missing1]</code>, …), so a reference that no longer points at its element still shows.`
 			: ''
 	} It catches what a screenshot can't: an attribute, an order under a cover, a lost space.</p>
-  <p><strong>Status:</strong> every page is compared whatever it answers (a 404 page too), and its HTTP status is shown beside it; two different statuses are a difference. <strong>Images:</strong> each shot waits up to ${report.options.imageWait} s for the images that have started loading; a shot that gave up says so.</p>
+  <p><strong>Status:</strong> every page is compared whatever it answers (a 404 page too), and its HTTP status is shown beside it; two different statuses are a difference. <strong>Images:</strong> each shot waits up to ${report.options.imageWait} s for the images that have started loading; a shot that gave up says so.${
+		report.options.css ? ` <strong>CSS</strong> (<code>--css</code>) added to both pages before each shot: <code>${escape(report.options.css)}</code>.` : ''
+	}</p>
 </header>
 ${rows}
 </body>
@@ -843,8 +855,9 @@ async function main() {
 			usage(`--mask-ids isn't a regular expression: ${error instanceof Error ? error.message : error}`);
 		}
 	}
+	const css = args.css ?? '';
 	const htmlOptions = { ignore: ignoredAttributes(args['ignore-attr']), maskIds };
-	const known = new Set(['playwright', 'old', 'new', 'pages', 'out', 'widths', 'image-wait', 'ignore-attr', 'mask-ids']);
+	const known = new Set(['playwright', 'old', 'new', 'pages', 'out', 'widths', 'image-wait', 'ignore-attr', 'mask-ids', 'css']);
 	for (const key of Object.keys(args)) if (!known.has(key)) usage(`unknown option --${key}`);
 
 	const chromium = await loadPlaywright(args.playwright ?? process.env.LOOK_SAME_PLAYWRIGHT);
@@ -885,8 +898,8 @@ async function main() {
 				const newUrl = joinUrl(args.new, path);
 				const result = { path, width, oldUrl, newUrl, files };
 				try {
-					const oldShot = await shoot(browser, oldUrl, width, imageWait * 1000);
-					const newShot = await shoot(browser, newUrl, width, imageWait * 1000);
+					const oldShot = await shoot(browser, oldUrl, width, imageWait * 1000, css);
+					const newShot = await shoot(browser, newUrl, width, imageWait * 1000, css);
 					writeFileSync(join(out, files.old), oldShot.png);
 					writeFileSync(join(out, files.new), newShot.png);
 					const { diff, ...score } = compare(oldShot.png, newShot.png);
@@ -929,7 +942,7 @@ async function main() {
 		generated: new Date().toISOString(),
 		score: `differingShare: of the pixels both screenshots cover, the share differing in any colour channel by more than ${TOLERANCE}/255. heightDelta: new height minus old, in CSS pixels.`,
 		tolerance: TOLERANCE,
-		options: { widths, imageWait, ignoreAttr: args['ignore-attr'] ?? null, maskIds: maskIds ? (args['mask-ids'] === 'auto' ? `auto (${AUTO_IDS.source})` : maskIds.source) : null },
+		options: { widths, imageWait, ignoreAttr: args['ignore-attr'] ?? null, maskIds: maskIds ? (args['mask-ids'] === 'auto' ? `auto (${AUTO_IDS.source})` : maskIds.source) : null, css: css || null },
 		status: 'status: the HTTP status each side answered, { old, new }. statusDiffers: true when they differ, which is a difference, not an error. imageCap (results only, when present): the shot gave up waiting for images after imageWait seconds; per side, how many were still loading and the first few addresses.',
 		results,
 		htmlScore:

package/skills/caracms-blocks/SKILL.md

@@ -124,7 +124,18 @@ const { block, cms } = Astro.props;
     width / height) for a fluid image, or a CSS `width` and/or `height` for a fixed one;
     `fit: 'contain'` to fit instead of crop. The block's CSS sizes it through `class`.
     It takes the element's own attributes (`id`, `title`, `draggable`, `aria-*`,
-    `data-*`) too.
+    `data-*`) too. With an empty value it draws nothing for visitors and, in a preview,
+    a dashed placeholder the editor can click to pick the image. So call it as
+    `(block.media || cms.preview) && <Media …/>`, not `block.media && …`, wherever an
+    empty slot should still be reachable on the page.
+  - **A media value reaches the block resolved, not as stored.** Where the file has
+    `{ key, alt, focal, w, h }` or `{ video, play, poster: 12.5 }`, the block gets
+    `{ kind: 'image', key, alt, decorative, focal, position, w, h }` or
+    `{ kind: 'video', playbackId, play, name, mp4, poster: <url>, duration, w, h }`
+    (`poster` is Mux's still as a URL, `w`, `h` and `duration` are numbers or `null`;
+    `block.media` is `null` when the slot is empty). A site helper that reads a media
+    value (a hero's poster, a video's `playbackId`) reads this shape; use `kind` to tell
+    the two apart.
 - `cms` is the render context: `cms.preview` (a preview render), `cms.first`,
   `cms.index`, `cms.read` (other documents, below). For "the first block on the page"
   (an eager hero, a heading that opens the page) use `cms.first`, true for the first
@@ -165,6 +176,8 @@ journal: { kind: 'sections', folder: 'content/journal', urlBase: '/journal/', fi
   static part is that `urlBase` (`src/pages/work/[slug].astro`, rendering with
   `RenderDocument` from `caracms/components/RenderDocument.astro` and `listDocuments` /
   `readDocument` from `caracms/content`, as `src/pages/[...path].astro` does for pages).
+  Its `getStaticPaths` leaves out entries with a `warning` (a file that can't be opened) and
+  `hidden` ones (a page hidden from the site, or one under it): those answer the 404 page.
   Every other route in `src/pages/` is the site's own code, and its address can't hold a
   document.
 - Shared blocks (`content/shared/`) and Site Settings are built in; no config.
@@ -192,6 +205,11 @@ const settings = await siteSettings(site, Astro.locals);
 ---
 ```
 
+**A block that needs Site Settings** (a form block showing the site's phone number) reads
+them the same way, with `siteSettings(site, Astro.locals)`: in a preview it reads the
+editor's draft, so an edit to Site Settings shows in the block too. `cms.read` is for
+collections only; it doesn't reach Site Settings.
+
 ## Text styles and lockups
 
 A lockup is a heading whose lines are set by the editor and fitted to their box in a
@@ -247,13 +265,33 @@ editor's preview alike. It gets `PageProps` (`caracms/document`): `document`,
   home page's own `seo.title`.) The ` · ` is the
   config's `titleSeparator`, spaces included: `titleSeparator: ' | '` beside `page` in
   `defineSite({ … })` keeps a site's old `About | Fernhill`. It's code, not a Site
-  Settings field: the title's format is design. A code route builds its title the same way
+  Settings field: the title's format is design. `titleFallback: 'site'` beside it makes every
+  page without its own `seo.title` fall back as the home page does (Site Settings'
+  `seo.title`, then the brand name); the default is `'page-and-brand'`. A code route builds its title the same way
   from `siteSettings`: `` `${title}${settings.seo.titleSeparator}${settings.brand.name}` ``. `<Blocks>` renders the blocks (or a fields document through its
   collection's component).
 - `document.kind === 'shared'` is a shared block's own preview: render it without the
   header and footer.
-- `<Media>` needs a block's `cms`, so images in the page's frame (a logo) stay the site's
-  own files.
+- **An image in the page's frame** (a header logo, a mega-menu photo, a footer badge) is a
+  `media()` field in Site Settings, drawn with `settingsImageUrl` from `caracms/content`
+  (`<Media>` needs a block's `cms`, which the frame doesn't have):
+
+  ```astro
+  ---
+  import { settingsImageUrl, siteSettings } from 'caracms/content';
+  import { site } from 'virtual:caracms/config';
+  const settings = await siteSettings(site, Astro.locals);
+  const photo = settingsImageUrl(settings.megaPhoto, { width: 640, height: 400 });
+  ---
+  <div class="mega" data-image={photo ?? '/images/placeholder.svg'}></div>
+  ```
+
+  It gives one URL by `<Media>`'s rules: one side is a `fit`, both are a `fill` cropped to
+  the focal point, a GIF or an SVG passes through unresized, no size is a `fit` at 1920. Ask
+  for the size it's shown at (twice it for a sharp 2× screen); there's no `srcset`. It's
+  null when the field is empty or the media isn't set up, so give the frame a fallback. It
+  works in the build, in the editor's preview (the draft's image) and under
+  `CARACMS_MEDIA=memory`.
 
 ## Forms
 
@@ -274,6 +312,33 @@ Draw it in a block with `<Form form="contact" preview={cms.preview} submit="Send
 `select({ options: [{ value: 'contact', label: 'Contact' }] })`. Submissions land in the
 editor's inbox and are emailed to Site Settings' `formRecipients` for that form.
 
+A field can also take `help`, `placeholder` (text, email, tel, textarea), `prefix` (text,
+tel), `error` (its own error line), `autocomplete`, and on a textarea `rows` (its height in
+lines, 1 to 50; default 6).
+
+The markup's classes are `.cms-form`, `.cms-form-field`, `.cms-form-label`,
+`.cms-form-help`, `.cms-form-error`, `.cms-form-submit` and `.cms-form-status`. For a
+site that draws its own look, `<Form>` takes, each optional (left out, it renders as
+without them):
+
+- `class`, and any other attribute (`data-reveal`, `id`, `aria-*`), on the `<form>`. The
+  form's own attributes (`action`, `method`, its `data-caracms-*`…) can't be replaced.
+- `submitClass`: classes on the submit button, beside `cms-form-submit`
+  (`submitClass="btn btn-primary"`).
+- `thanks`: the line after a send, in place of "Thanks, we'll be in touch shortly."
+  `failed`: the line when a send fails, in place of "Something went wrong. Please email
+  us directly." (when the endpoint gives its own sentence, that shows instead).
+- `errors`: each field type's error line, in place of the package's wording:
+  `errors={{ email: 'Please check your email address.' }}`. A field's own `error` still wins.
+- `actions`: wraps the button and the status line in `<div class="cms-form-actions">`, so
+  the site's CSS can set them in a row.
+- `labelPlaceholders`: a field that can take a placeholder and sets none uses its label.
+
+```astro
+<Form form="contact" preview={cms.preview} class="contact-form" data-reveal
+	submitClass="btn btn-primary" thanks="Thanks — we'll be in touch." actions labelPlaceholders />
+```
+
 ## Scripts and the live preview
 
 The editor shows the page in iframes, through the same page component with

package/skills/caracms-content/SKILL.md

@@ -58,7 +58,8 @@ A page (`sections`):
   (`<title> · <brand name>`, unless `seo.title` is set; the config's `titleSeparator` can
   make the ` · ` another separator); it isn't necessarily drawn on the page. The home page
   is the exception: its title is its own `seo.title`, else Site Settings' `seo.title`, else
-  the brand name (the document's `title` only when all of those are empty).
+  the brand name (the document's `title` only when all of those are empty). With the
+  config's `titleFallback: 'site'`, every page falls back that way, not only the home page.
 - Each block is `{ "type": <a key of the config's blocks>, ...its fields }`. A field left
   out reads as empty.
 - `{ "shared": "<name>" }` places the shared block `content/shared/<name>.json` there.