caracms 0.0.0-stage → 0.2.0

package/src/components/MediaPlayer.astro

@@ -0,0 +1,102 @@
+---
+/**
+ * A clip that plays as a player (M5b Decision 4), drawn by Media.astro: its poster
+ * (Mux's WebP still) and one real `<button>`, "Play video: {name}" ("Play video" with
+ * no name). The first click imports `@mux/mux-player` and swaps in `<mux-player>`
+ * with sound (media-player.ts). Only this component carries a script, so a page
+ * without a player ships none.
+ *
+ * The caller's `class` and `style` go on the frame (`.cms-player`), which the block's
+ * CSS sizes; the poster covers it. The button's look is the site's to restyle
+ * (`.cms-player-button`); the defaults here only make it usable.
+ */
+import type { RenderClip } from '../media-value.ts';
+
+interface Props {
+	clip: RenderClip;
+	loading: 'eager' | 'lazy';
+	fetchpriority?: 'high' | 'low' | 'auto';
+	class?: string;
+	style?: string;
+	markers?: Record<string, unknown>;
+}
+
+const { clip, loading, fetchpriority, class: className, style, markers = {} } = Astro.props;
+const label = clip.name ? `Play video: ${clip.name}` : 'Play video';
+const length = (() => {
+	if (!clip.duration) return '';
+	const total = Math.round(clip.duration);
+	return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
+})();
+---
+
+<div class:list={['cms-player', className]} style={style} data-caracms-player data-playback-id={clip.playbackId} data-name={clip.name} data-poster={clip.poster} {...markers}>
+	<img class="cms-player-poster" src={clip.poster} alt="" width={clip.w ?? undefined} height={clip.h ?? undefined} loading={loading} fetchpriority={fetchpriority} decoding="async" />
+	<button type="button" class="cms-player-button" aria-label={label} data-caracms-play>
+		<span class="cms-player-icon" aria-hidden="true"></span>
+		<span aria-hidden="true">Play video</span>
+		{length && <small aria-hidden="true">{length}</small>}
+	</button>
+</div>
+
+<script>
+	import { initPlayers } from './media-player.ts';
+
+	initPlayers();
+</script>
+
+<style is:global>
+	.cms-player {
+		position: relative;
+		overflow: hidden;
+	}
+
+	.cms-player-poster,
+	.cms-player mux-player {
+		position: absolute;
+		inset: 0;
+		display: block;
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+	}
+
+	.cms-player-button {
+		position: absolute;
+		left: 1rem;
+		bottom: 1rem;
+		display: inline-flex;
+		align-items: center;
+		gap: 0.625rem;
+		padding: 0.5rem 1.125rem 0.5rem 0.5rem;
+		border: 0;
+		border-radius: 999px;
+		background: #fff;
+		color: #111;
+		font: inherit;
+		font-weight: 600;
+		cursor: pointer;
+	}
+
+	.cms-player-icon {
+		display: grid;
+		place-items: center;
+		width: 2rem;
+		height: 2rem;
+		border-radius: 50%;
+		background: #111;
+	}
+
+	.cms-player-icon::after {
+		content: '';
+		margin-left: 3px;
+		border-left: 10px solid #fff;
+		border-top: 6px solid transparent;
+		border-bottom: 6px solid transparent;
+	}
+
+	.cms-player.is-playing .cms-player-poster,
+	.cms-player.is-playing .cms-player-button {
+		display: none;
+	}
+</style>

package/src/components/RenderDocument.astro

@@ -0,0 +1,64 @@
+---
+/**
+ * A whole page from a document, through the site's page component. Phase 2's
+ * preview route renders this with `preview` on:
+ *
+ *   const document = normaliseAnyDocument(posted, site, collection);   // document.ts
+ *   <RenderDocument document={document} collection="pages" preview />
+ *
+ * The document is any kind a page shows (M5a): a section builder's, a list-of-fields
+ * document (rendered through its collection's component) or a shared block alone.
+ * The page component passes `collection` on to `<Blocks>`.
+ *
+ * With `preview`, the package's components emit their `data-cms-*` markers and
+ * plain text fields are contenteditable (Decision 17). Without, it's the public page.
+ *
+ * M6c (G2): the page component also gets `data`, the document's own fields' render
+ * data (a section builder's page fields, a fields document's fields), read from the
+ * render's source as a block's are. M7 (Decision 13): and `settings`, Site Settings' render
+ * data from the same source (read.ts → settingsRenderData), so a preview shows the draft's.
+ *
+ * Posts and tags (Decision 12): a route may pass `listPage`, the page of a paged listing
+ * (`/journal/page/2` renders the journal page with `listPage={2}`); 1 by default, and always 1
+ * in a preview. The page component gets it, and `read`, the reader its blocks get.
+ *
+ * MEC trial item 2: the page component gets `path`, its document's address (head.ts →
+ * documentPath): a public render's from the address it's served at, a preview's from its
+ * document (`previewPath`, the preview route's `path`; else the GET's `?path=`).
+ */
+import { Page } from 'virtual:caracms/page';
+import { site } from 'virtual:caracms/config';
+import { documentUrl } from '../content.ts';
+import { own, type AnyDocument, type PageProps } from '../document.ts';
+import { documentPath } from '../head.ts';
+import { documentReader, renderFields, renderSourceOf, settingsRenderData } from '../read.ts';
+
+/** Any document a reader gives (content.ts → readDocument); Site Settings has no page, so it's refused. */
+type Props = Omit<PageProps, 'document' | 'data' | 'settings' | 'listPage' | 'read' | 'path'> & {
+	document: AnyDocument;
+	listPage?: number;
+	/** A preview's document path in its collection (`index`, `services/branding`): the preview route gives it, as a POST's URL has no `?path=`. */
+	previewPath?: string;
+};
+
+const { document, collection, preview = false } = Astro.props;
+// Posts and tags, Decision 12: a preview is always page 1; anything that isn't a whole number from 1 reads as 1.
+const listPage = !preview && Number.isInteger(Astro.props.listPage) && Astro.props.listPage! >= 1 ? Astro.props.listPage! : 1;
+if (document.kind === 'settings') throw new Error('<RenderDocument>: Site Settings has no page of its own.');
+const fields = own(site.collections, collection)?.fields ?? null;
+const values = document.kind === 'shared' ? undefined : document.data;
+const source = renderSourceOf(Astro.locals);
+const reader = documentReader(site, source);
+const data = fields && values ? await renderFields(fields, values, reader) : {};
+const settings = await settingsRenderData(site, source, reader);
+const previewOf = Astro.props.previewPath ?? Astro.url.searchParams.get('path');
+const ownCollection = own(site.collections, collection);
+const path = documentPath({
+	preview,
+	previewUrl: preview && ownCollection && previewOf ? documentUrl(ownCollection, previewOf) : null,
+	pathname: Astro.url.pathname,
+	listPage,
+});
+---
+
+<Page document={document} collection={collection} path={path} preview={preview} data={data} settings={settings} listPage={listPage} read={reader} />

package/src/components/RichText.astro

@@ -0,0 +1,59 @@
+---
+/**
+ * A rich-text field (M5a Decision 3): semantic HTML with no classes and no script.
+ *
+ *   <RichText cms={cms} field="body" value={block.body} class="text-body" />
+ *
+ * - `<p>`, `<h2>`, `<h3>`, `<ul>`/`<ol>` with `<li>`; `<strong>`, `<em>`, `<br>`;
+ *   `<a href>` for a link that passes the link rule, its text otherwise (Decision 4).
+ *   A heading with a break renders as Text's multi-line heading does: its lines
+ *   joined by `<br>`.
+ * - A kind the field doesn't allow renders as `<p>`, and a link where the field
+ *   has links off as its text (the field warns; rich-text.ts reads them so).
+ * - The blocks sit in one wrapper element, `as` (default `div`; a heading field's below), which takes
+ *   `class` and any other attribute. Public render: nothing at all for an empty value.
+ * - Preview render only (M3 Decision 17): the wrapper is always there, with
+ *   `data-cms-field="<path>" data-cms-kind="richText"`. A top-level field is typed
+ *   on the page (on-page rich text, Decisions 1 and 5): it also gets `tabindex="0"`,
+ *   so Tab and a tap can reach it, and /admin mounts its page editor on this very
+ *   element (preview/page-editor.ts). Never contenteditable in the render: the page
+ *   editor adds that while mounted, and takes it away again. A nested path
+ *   (`items.0.body`) is edited in the sidebar only, so it has no tabindex. The public
+ *   render has none of these.
+ * - `field` is the field's key, or a dotted path into a list (Decision 16).
+ * - **A heading field** (`richText({ heading: true })`, M9 Decision 11): the element is
+ *   `as`, or `h1` when it holds the page's first heading and `h2` otherwise (as Text's
+ *   heading), and inside it each paragraph's runs, the paragraphs joined by `<br>`: no
+ *   `<p>`. Bold is `<strong>`, so the site styles it (`h1 strong { … }`).
+ *
+ *     <RichText cms={cms} field="statement" value={block.statement} class="board-statement" />
+ */
+import { site } from 'virtual:caracms/config';
+import type { HTMLTag } from 'astro/types';
+import type { BlockContext } from '../document.ts';
+import { parseField } from '../fields.ts';
+import { richHeadingHtml, richTextHtml, type RichTextValue } from '../rich-text.ts';
+import { isTypedOnPage, requireField } from './descriptor.ts';
+import { passThrough } from './attributes.ts';
+
+interface Props {
+	cms: BlockContext;
+	field: string;
+	value: RichTextValue;
+	as?: HTMLTag;
+	class?: string;
+	[attribute: string]: unknown;
+}
+
+const { cms, field, value, as, class: className, ...given } = Astro.props;
+// M8 trial (item 4): a bare attribute stays bare, false is none (attributes.ts).
+const rest = passThrough(given);
+const descriptor = requireField(site, cms, field, 'richText', 'RichText');
+const Tag = as ?? (descriptor.heading ? (cms.h1Field === field ? 'h1' : 'h2') : 'div');
+// Re-read through the field, so a value from anywhere renders by the field's rules.
+const parsed = parseField(descriptor, value) as RichTextValue;
+const html = descriptor.heading ? richHeadingHtml(parsed) : richTextHtml(parsed, { fileLinks: true });
+const markers = cms.preview ? { 'data-cms-field': field, 'data-cms-kind': 'richText', ...(isTypedOnPage(field) ? { tabindex: '0' } : {}) } : {};
+---
+
+{(html !== '' || cms.preview) && <Tag class={className} {...rest} {...markers} set:html={html} />}

package/src/components/Text.astro

@@ -0,0 +1,81 @@
+---
+/**
+ * A text field, one line or several (Decision 12; the line-break rule: a break is
+ * stored as `\n` and rendered as `<br>`, nothing else breaks the text).
+ *
+ *   <Text cms={cms} field="intro" value={block.intro} class="hero-intro" />
+ *
+ * - The element: `as`, or for a field marked `heading: true`, `h1` when it holds
+ *   the page's first heading (Decision 16) and `h2` otherwise; `p` by default.
+ * - Public render: an empty value renders nothing.
+ * - Preview render (Decision 17): always rendered, so it can be typed into, with
+ *   `data-cms-field="<field>" data-cms-kind="text"` and `contenteditable="plaintext-only"`
+ *   (plain text fields are edited on the page, Decision 12). The block's index is
+ *   on the nearest `[data-cms-block]` ancestor (Block.astro).
+ * - `field` is the field's key, or a dotted path into a list (M5a Decision 16):
+ *   `<Text cms={cms} field={`credits.${i}.name`} value={credit.name} />` in the
+ *   block's own loop. The marker carries the path. Text inside a list is edited in
+ *   the sidebar (Decision 13), so a nested path is never `contenteditable`.
+ * - **The lines rendering** (M9 Decision 10), for a field declared `text({ lines: true })`:
+ *   each line is drawn trimmed and blank lines draw nothing; with one line left it's drawn unwrapped; with more, each
+ *   line is a `<span>` with `lineClass` (Share's `block text-balance`), and no `<br>`.
+ *   In a preview each span also carries `data-cms-line`, so the text read back from the
+ *   page (preview/field-text.ts) starts a new line at each, and the element carries
+ *   `data-cms-lines` (and `data-cms-line-class`), so a sidebar edit is drawn the same way.
+ *
+ *     <Text cms={cms} field="heading" value={block.heading} lineClass="block text-balance" />
+ */
+import { site } from 'virtual:caracms/config';
+import type { HTMLTag } from 'astro/types';
+import type { BlockContext } from '../document.ts';
+import { isTypedOnPage, requireField } from './descriptor.ts';
+import { passThrough } from './attributes.ts';
+
+interface Props {
+	cms: BlockContext;
+	field: string;
+	value: string;
+	as?: HTMLTag;
+	class?: string;
+	/** The lines rendering's class on each line's `<span>` (M9 Decision 10). */
+	lineClass?: string;
+	/** Anything else (such as the caller's scoped-style attribute) goes on the element. */
+	[attribute: string]: unknown;
+}
+
+const { cms, field, value, as, class: className, lineClass, ...given } = Astro.props;
+// M8 trial (item 4): a bare attribute stays bare, false is none (attributes.ts).
+const rest = passThrough(given);
+const descriptor = requireField(site, cms, field, 'text', 'Text');
+const Tag = as ?? (descriptor.heading ? (cms.h1Field === field ? 'h1' : 'h2') : 'p');
+const typed = value ? (descriptor.multiline ? value.split('\n') : [value]) : [];
+// M9 Decision 10: blank lines draw nothing, and two or more lines are a span each.
+// Each line is drawn trimmed, as Tina's toLines() did (port friction 7); the stored value keeps its spaces.
+const lines = descriptor.lines ? typed.map((line) => line.trim()).filter((line) => line !== '') : typed;
+const spans = descriptor.lines && lines.length > 1;
+const lineMarker = cms.preview ? { 'data-cms-line': '' } : {};
+// The preview writes a sidebar edit back as these lines (preview/field-text.ts → writeFieldText).
+const linesMarkers = cms.preview && descriptor.lines ? { 'data-cms-lines': '', ...(lineClass ? { 'data-cms-line-class': lineClass } : {}) } : {};
+const markers = cms.preview
+	? { 'data-cms-field': field, 'data-cms-kind': 'text', ...(isTypedOnPage(field) ? { contenteditable: 'plaintext-only' } : {}) }
+	: {};
+---
+
+{
+	(lines.length > 0 || cms.preview) && (
+		<Tag class={className} {...rest} {...markers} {...linesMarkers}>
+			{spans
+				? lines.map((line) => (
+						<span class={lineClass} {...lineMarker}>
+							{line}
+						</span>
+					))
+				: lines.map((line, i) => (
+						<>
+							{i > 0 && <br />}
+							{line}
+						</>
+					))}
+		</Tag>
+	)
+}

package/src/components/attributes.ts

@@ -0,0 +1,33 @@
+/**
+ * The attributes a caller passes through a package component (`<Block data-home-hero>`,
+ * `<Text … hidden={!open}>`), as they'd render on a plain element in Astro (M8 trial,
+ * item 4). A prop written bare reaches a component as `true`, and Astro's spread writes
+ * `true` as `="true"` for most attributes; on a plain element the source's bare attribute
+ * stays bare. So:
+ *
+ * - `true` is a bare attribute (`data-home-hero`, not `data-home-hero="true"`);
+ * - `false`, `undefined` and `null` are no attribute at all (kept as `undefined`, so a
+ *   caller's `download={false}` still overrides what the component would add);
+ * - anything else passes as given.
+ *
+ * Except where `"true"` and `"false"` are the attribute's own values, which Astro writes as
+ * text on a plain element too: `aria-*`, `draggable`, `contenteditable`, `spellcheck` and
+ * `writingsuggestions` pass unchanged (`aria-hidden={true}` stays `aria-hidden="true"`).
+ *
+ * Browser-safe, no imports.
+ */
+const TRUE_FALSE_VALUES = new Set(['draggable', 'contenteditable', 'spellcheck', 'writingsuggestions']);
+
+const keepsBooleans = (name: string) => name.startsWith('aria-') || TRUE_FALSE_VALUES.has(name.toLowerCase());
+
+/** The pass-through attributes with booleans as a plain element renders a bare attribute. */
+export function passThrough(attributes: Record<string, unknown>): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const [name, value] of Object.entries(attributes)) {
+		if (typeof value === 'boolean' && keepsBooleans(name)) out[name] = value;
+		else if (value === true) out[name] = '';
+		else if (value === false || value === null) out[name] = undefined;
+		else out[name] = value;
+	}
+	return out;
+}

package/src/components/descriptor.ts

@@ -0,0 +1,45 @@
+/**
+ * Where the package's field components find a field's descriptor from the path
+ * they're given (M5a Decision 16): a block's schema, or, in a fields document's
+ * render (`cms.collection`, Decision 7), its collection's fields. Every component
+ * looks up here, so all of them work in both.
+ */
+import type { ResolvedSite } from '../config.ts';
+import { own, type BlockContext } from '../document.ts';
+import { fieldAtPath, isKeyPath, type Field, type Fields } from '../fields.ts';
+
+type Site = Pick<ResolvedSite, 'blocks' | 'collections'>;
+
+/** The fields the context's paths point into: its fields document's, else its block's. */
+function fieldsOf(site: Site, cms: BlockContext): Fields | undefined {
+	if (cms.collection) return own(site.collections, cms.collection)?.fields ?? undefined;
+	return own(site.blocks, cms.type)?.fields;
+}
+
+/** "block "hero"" or "collection "case-studies"", for messages. */
+const whose = (cms: BlockContext) => (cms.collection ? `collection "${cms.collection}"` : `block "${cms.type}"`);
+
+/**
+ * The descriptor at a dotted path (`heading`, `credits.1.name`, `cta`) in the
+ * context's schema, with what's left of the path past it; undefined when the path
+ * names no field.
+ */
+export function descriptorAt(site: Site, cms: BlockContext, path: string): { field: Field; rest: string[] } | undefined {
+	const fields = fieldsOf(site, cms);
+	return fields ? fieldAtPath(fields, path) : undefined;
+}
+
+/** The descriptor a component needs, or a plain error naming the component, the block (or collection) and the path. */
+export function requireField<K extends Field['kind']>(site: Site, cms: BlockContext, path: string, kind: K, component: string): Extract<Field, { kind: K }> {
+	const found = descriptorAt(site, cms, path);
+	if (!found || found.rest.length > 0 || found.field.kind !== kind) {
+		throw new Error(`<${component}>: ${whose(cms)} has no ${kind} field "${path}"`);
+	}
+	return found.field as Extract<Field, { kind: K }>;
+}
+
+/**
+ * Only a path with no list index is typed on the page (Decision 13): a top-level field,
+ * or one in a group (`left.heading`). A list item's fields open in the sidebar.
+ */
+export const isTypedOnPage = (path: string) => isKeyPath(path);

package/src/components/form-client.ts

@@ -0,0 +1,182 @@
+/**
+ * The public form's one small script (M6 Decision 17), on a page with a form only
+ * (Form.astro carries it). It enhances a form that already works without it:
+ *
+ * - submits with `fetch` (`Accept: application/json`), shows "Sending…", then the
+ *   thanks line, or the endpoint's own sentence when it gave one (the thanks and the
+ *   failure lines are the form's `data-thanks` / `data-failed` when Form.astro was given them);
+ * - makes a files field's picks add up: each pick is added to the files already chosen
+ *   (the real list kept in a `DataTransfer` and given back to `input.files`, so the fetch
+ *   and a plain submit both send every one), the same name and size never twice, listed
+ *   under the input with each one's size and a Remove button. A pick that would pass a
+ *   limit (5 files, 25 MB in all, the kinds) adds nothing past it and says the endpoint's
+ *   own sentence in the status line;
+ * - checks the chosen files against the limits before sending (the endpoint checks
+ *   them again; this only spares a visitor a refused upload);
+ * - turns `?sent=1` (the no-JS reply) into the thanks line and drops it from the address;
+ * - renders the Turnstile widget when the form has a site key (api.js loaded once,
+ *   explicit render), and mints a fresh token after each send.
+ *
+ * A port of the template's Form section script (`forms.md` → The Form section). If
+ * anything here throws before `preventDefault`, the form is still a working native post.
+ */
+
+const THANKS = "Thanks, we'll be in touch shortly.";
+const FAILED = 'Something went wrong. Please email us directly.';
+
+interface Turnstile {
+	render: (el: HTMLElement, opts: Record<string, unknown>) => string;
+	reset: (container?: string | HTMLElement) => void;
+}
+type TurnstileWindow = Window & { turnstile?: Turnstile; __caracmsTurnstile?: () => void };
+const turnstile = () => (window as TurnstileWindow).turnstile;
+
+let apiJs: Promise<void> | undefined;
+function loadTurnstile(): Promise<void> {
+	if (turnstile()) return Promise.resolve();
+	apiJs ??= new Promise((resolve) => {
+		(window as TurnstileWindow).__caracmsTurnstile = resolve;
+		const s = document.createElement('script');
+		s.src = 'https://challenges.cloudflare.com/turnstile/v0/api.js?onload=__caracmsTurnstile&render=explicit';
+		s.async = true;
+		document.head.appendChild(s);
+	});
+	return apiJs;
+}
+
+/** Why the chosen files can't be sent, or ''. */
+function filesProblem(form: HTMLFormElement): string {
+	const maxFiles = Number(form.dataset.maxFiles);
+	const maxBytes = Number(form.dataset.maxBytes);
+	if (!maxFiles || !maxBytes) return '';
+	const files = [...form.querySelectorAll<HTMLInputElement>('input[type="file"]')].flatMap((input) => [...(input.files ?? [])]);
+	if (files.length > maxFiles) return `Attach up to ${maxFiles} files (you chose ${files.length}).`;
+	const bytes = files.reduce((sum, file) => sum + file.size, 0);
+	if (bytes > maxBytes) return `That's too much to send: attachments can come to ${Math.round(maxBytes / 1024 / 1024)} MB in all. Send fewer or smaller files, or email them to us.`;
+	return '';
+}
+
+// No `<` here: the page's check reads this inline script as text with no `<` in it (build-output tests).
+const size = (n: number) => (n >= 1024 * 1024 ? `${(n / 1024 / 1024).toFixed(n >= 10 * 1024 * 1024 ? 0 : 1)} MB` : n >= 1024 ? `${Math.round(n / 1024)} KB` : `${n} bytes`);
+
+/** A files field's picks add up, listed with Remove (see above). Without `DataTransfer`, it stays the native input. */
+function enhanceFiles(form: HTMLFormElement, say: (text: string, failed: boolean) => void): void {
+	const input = form.querySelector<HTMLInputElement>('input[type="file"]');
+	const list = form.querySelector<HTMLUListElement>('[data-caracms-files]');
+	if (!input || !list || typeof DataTransfer !== 'function') return;
+	const maxFiles = Number(form.dataset.maxFiles);
+	const maxBytes = Number(form.dataset.maxBytes);
+	const exts = input.accept.split(',').map((e) => e.trim().replace(/^\./, '').toLowerCase());
+	let chosen: File[] = [];
+	const sync = () => {
+		const dt = new DataTransfer();
+		for (const f of chosen) dt.items.add(f);
+		input.files = dt.files;
+		list.replaceChildren(
+			...chosen.map((f, i) => {
+				const li = document.createElement('li');
+				li.className = 'cms-form-file';
+				const name = document.createElement('span');
+				name.className = 'cms-form-file-name';
+				name.textContent = f.name;
+				const bytes = document.createElement('span');
+				bytes.className = 'cms-form-file-size';
+				bytes.textContent = size(f.size);
+				const remove = document.createElement('button');
+				remove.type = 'button';
+				remove.className = 'cms-form-file-remove';
+				remove.textContent = 'Remove';
+				remove.setAttribute('aria-label', `Remove ${f.name}`);
+				remove.addEventListener('click', () => {
+					chosen = chosen.filter((_, j) => j !== i);
+					sync();
+					(list.querySelectorAll<HTMLButtonElement>('.cms-form-file-remove')[Math.min(i, chosen.length - 1)] ?? input).focus();
+				});
+				li.append(name, ' ', bytes, ' ', remove);
+				return li;
+			}),
+		);
+		list.hidden = chosen.length === 0;
+	};
+	input.addEventListener('change', () => {
+		const picked = [...(input.files ?? [])].filter((f) => !chosen.some((c) => c.name === f.name && c.size === f.size));
+		const next = [...chosen];
+		let problem = '';
+		for (const f of picked) {
+			const ext = /\.([^.]+)$/.exec(f.name)?.[1]?.toLowerCase() ?? '';
+			if (!exts.includes(ext)) problem ||= `${f.name}: we can't take that kind of file. Send ${form.dataset.fileKinds} files.`;
+			else if (next.length >= maxFiles) problem ||= `Attach up to ${maxFiles} files (you chose ${chosen.length + picked.length}).`;
+			else if (next.reduce((sum, x) => sum + x.size, f.size) > maxBytes) problem ||= `That's too much to send: attachments can come to ${Math.round(maxBytes / 1024 / 1024)} MB in all. Send fewer or smaller files, or email them to us.`;
+			else next.push(f);
+		}
+		chosen = next;
+		sync();
+		say(problem, !!problem);
+	});
+	form.addEventListener('reset', () => {
+		chosen = [];
+		// After the reset has emptied the input.
+		setTimeout(sync);
+	});
+}
+
+function enhance(form: HTMLFormElement): void {
+	if (form.dataset.caracmsFormReady) return;
+	form.dataset.caracmsFormReady = '1';
+	const status = form.querySelector<HTMLElement>('[data-caracms-form-status]');
+	if (!status) return;
+	const submit = form.querySelector<HTMLButtonElement>('button[type="submit"]');
+	const widget = form.querySelector<HTMLElement>('[data-caracms-turnstile]');
+	const thanks = form.dataset.thanks || THANKS;
+	const failedLine = form.dataset.failed || FAILED;
+	const say = (text: string, failed: boolean) => {
+		status.textContent = text;
+		status.classList.toggle('cms-form-failed', failed);
+	};
+
+	enhanceFiles(form, say);
+
+	if (widget?.dataset.sitekey) {
+		const sitekey = widget.dataset.sitekey;
+		void loadTurnstile().then(() => turnstile()?.render(widget, { sitekey, appearance: 'always', theme: 'light' }));
+	}
+
+	form.addEventListener('submit', async (event) => {
+		if (!form.reportValidity()) return;
+		event.preventDefault();
+		const tooMuch = filesProblem(form);
+		if (tooMuch) return say(tooMuch, true);
+		submit?.setAttribute('disabled', '');
+		say('Sending…', false);
+		let failure = failedLine;
+		try {
+			const res = await fetch(form.action, { method: 'POST', headers: { Accept: 'application/json' }, body: new FormData(form) });
+			if (!res.ok) {
+				const body = (await res.json().catch(() => null)) as { error?: unknown } | null;
+				if (typeof body?.error === 'string' && body.error && res.status !== 502) failure = body.error;
+				throw new Error(String(res.status));
+			}
+			form.reset();
+			say(thanks, false);
+		} catch {
+			say(failure, true);
+		} finally {
+			submit?.removeAttribute('disabled');
+			// Turnstile's tokens are single-use: a fresh one for the next send.
+			if (widget) turnstile()?.reset(widget);
+		}
+	});
+
+	// The no-JS path lands back here with ?sent=1.
+	const params = new URLSearchParams(location.search);
+	if (params.get('sent') === '1') {
+		say(thanks, false);
+		params.delete('sent');
+		const rest = params.toString();
+		history.replaceState(null, '', `${location.pathname}${rest ? `?${rest}` : ''}${location.hash}`);
+	}
+}
+
+export function initForms(): void {
+	for (const form of document.querySelectorAll<HTMLFormElement>('form[data-caracms-form]')) enhance(form);
+}

package/src/components/media-player.ts

@@ -0,0 +1,46 @@
+/**
+ * The player's one behaviour (M5b Decision 4; the template's `videoPlayer.ts`): on the
+ * first click, import `@mux/mux-player` (its own chunk, which nothing loads before),
+ * mount `<mux-player playback-id autoplay>` in the same frame with sound, and move
+ * focus to it. Browser only; imported only by MediaPlayer.astro's script, so a page
+ * without a player never loads it.
+ */
+export function initPlayers(): void {
+	for (const host of document.querySelectorAll<HTMLElement>('[data-caracms-player]')) {
+		if (host.dataset.caracmsReady) continue;
+		host.dataset.caracmsReady = '';
+		const button = host.querySelector<HTMLButtonElement>('[data-caracms-play]');
+		const { playbackId, name = '', poster = '' } = host.dataset;
+		if (!button || !playbackId) continue;
+		let busy = false;
+		button.addEventListener('click', async () => {
+			if (busy) return;
+			busy = true;
+			button.setAttribute('aria-busy', 'true');
+			try {
+				await import('@mux/mux-player');
+			} catch {
+				// The chunk didn't arrive (offline, blocked): the clip's MP4 is the fallback.
+				busy = false;
+				button.removeAttribute('aria-busy');
+				window.location.assign(`https://stream.mux.com/${encodeURIComponent(playbackId)}/highest.mp4`);
+				return;
+			}
+			const player = document.createElement('mux-player');
+			player.setAttribute('playback-id', playbackId);
+			player.setAttribute('stream-type', 'on-demand');
+			if (poster) player.setAttribute('poster', poster);
+			if (name) {
+				player.setAttribute('metadata-video-title', name);
+				player.setAttribute('aria-label', name);
+			}
+			player.setAttribute('playsinline', '');
+			player.setAttribute('autoplay', '');
+			host.classList.add('is-playing');
+			button.removeAttribute('aria-busy');
+			host.append(player);
+			if (!player.hasAttribute('tabindex')) player.tabIndex = -1;
+			player.focus({ preventScroll: true });
+		});
+	}
+}

package/src/components/media-props.ts

@@ -0,0 +1,35 @@
+/**
+ * `<Media>`'s props (Media.astro), in a module of their own so a test can type-check them
+ * (test/media-props.test.ts).
+ */
+import type { HTMLAttributes } from 'astro/types';
+import type { BlockContext } from '../document.ts';
+
+/**
+ * M8 trial (item 13): the element's own attributes (`draggable`, `id`, `title`, `data-*`…)
+ * type-check and pass through, on the `<img>`, the loop's `<video>` or the player. What the
+ * component sets itself (the sources, `alt`, the size) isn't the caller's.
+ */
+type Passed = Omit<HTMLAttributes<'img'>, 'src' | 'srcset' | 'alt' | 'sizes' | 'width' | 'height' | 'loading' | 'fetchpriority' | 'decoding' | 'class' | 'style'>;
+
+export interface MediaProps extends Passed {
+	cms: BlockContext;
+	/** The slot's dotted path in the block's (or fields document's) schema: its markers and its `only`/`play`. */
+	field?: string;
+	value: unknown;
+	/** Fluid: the rendered width at each breakpoint, from the block's CSS. */
+	sizes?: string;
+	/** Fluid: crop to this shape (width / height). */
+	ratio?: number;
+	minWidth?: number;
+	maxWidth?: number;
+	/** Fixed: the CSS size in px. */
+	width?: number;
+	height?: number;
+	fit?: 'cover' | 'contain';
+	loading?: 'eager' | 'lazy';
+	fetchpriority?: 'high' | 'low' | 'auto';
+	class?: string;
+	style?: string;
+	[attribute: `data-${string}`]: unknown;
+}