caracms 0.1.0 → 0.2.0

package/bin/init.mjs

@@ -43,6 +43,7 @@ const SKILL_BLURBS = {
 	'caracms-content': 'changing content: the JSON files in content/, rich text, images, references, Site Settings, and working on a branch',
 	'caracms-blocks': 'building the site: blocks and their fields, collections, text styles, the page component, forms, and scripts beside the editor',
 	'caracms-adopt': 'bringing the site\'s existing pages onto caracms, one page at a time, and checking they look the same',
+	'caracms-tina': 'porting a site built on Tina (a Tina template site) onto caracms with the reference conversion script, re-runnable on newer content',
 };
 
 const posix = (p) => p.split(sep).join('/');

package/bin/templates/catch-all.astro.txt

@@ -12,8 +12,9 @@ import { site } from 'virtual:caracms/config';
 export const prerender = true;
 
 export async function getStaticPaths() {
-	// A file that can't be opened (invalid JSON, no title, a nested index.json) has no page.
-	const entries = (await listDocuments(site, 'pages')).filter((e) => !e.warning);
+	// A file that can't be opened (invalid JSON, no title, a nested index.json) has no page,
+	// and nor has a hidden one (or one under it): visitors get the 404 page.
+	const entries = (await listDocuments(site, 'pages')).filter((e) => !e.warning && !e.hidden);
 	return entries.map((e) => ({ params: { path: e.path === 'index' ? undefined : e.path }, props: { path: e.path } }));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A visual CMS for Astro sites, with content in git.",
   "license": "MIT",
   "type": "module",

package/skills/caracms-adopt/SKILL.md

@@ -142,6 +142,11 @@ form, such as `<brand> | <tagline>`, goes in the home page's own `seo.title`
 the home page, where an editor changing it will look, and it wins whatever Site Settings
 holds.
 
+If the old site showed one site-wide title on every page without its own (a Tina template
+does), set the config's `titleFallback: 'site'` beside `titleSeparator`: step 2 then holds
+on every page, not only the home page (the paged-listing ` — page N` still follows). The
+default, `'page-and-brand'`, is the list above.
+
 **Per-page layout props.** The old routes often passed the layout something by hand: the
 header's colour or variant, `<main>`'s classes, a script in `<head>` for one page, the
 current page for the nav's highlight. A document has no route to do that, so the page
@@ -461,6 +466,13 @@ node .claude/skills/caracms-adopt/look-same.mjs --playwright /tmp/look-same \
     --pages pages.txt --out /tmp/look-same/report \
     --ignore-attr 'data-tina-*' --mask-ids auto
   ```
+- **An element that varies run to run on the old site itself** (a wordmark fitted to its box
+  while the display font loads, so two shots of the same build differ) can't be fixed by
+  either site. `--css <rules>` adds the same CSS to both pages just before each shot: hide
+  the element or pin its size, e.g.
+  `--css '[data-wordmark-wrap]{visibility:hidden!important}'`. It changes the shots only,
+  not the HTML diff, and the report names the rules; keep them to the one element, since
+  whatever they cover is no longer compared.
 - **Spaces**: a space between inline content shows as `␣` at the start of the next text,
   wherever it sat (`<span>sub </span><em>` and `<span>sub</span> <em>` are the same), and a
   space beside a block tag is dropped, since neither shows. So a `␣` line in the diff is a

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:
@@ -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);
 }
@@ -310,7 +315,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,
@@ -371,6 +376,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 +821,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 +851,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 +894,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 +938,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,7 +265,9 @@ 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
@@ -274,6 +294,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.