caracms 0.0.0-stage → 0.2.0

package/src/code-routes.ts

@@ -0,0 +1,134 @@
+/**
+ * Code routes (M8 Decision 10): the URLs the site's own `src/pages/` serves, which a
+ * document can't take. A page is either code or a document, never both.
+ *
+ * - **Read from the file names**, as Astro's file routing reads them (`srcDir` honoured
+ *   by the caller): `about.astro` is `/about`, `index.astro` its folder, `sitemap.xml.ts`
+ *   `/sitemap.xml`, `[slug]` and `[...rest]` are parameters. Endpoints count too. A file
+ *   or folder whose name starts with `_` or `.` isn't a route (Astro's rule).
+ * - **The documents' own routes reserve nothing:** a route with parameters whose static
+ *   prefix is a collection's `urlBase` (the catch-all `[...path].astro` at `/`,
+ *   `work/[slug].astro` at `/work/`).
+ * - **One per base.** When several routes with parameters sit at one collection's
+ *   `urlBase`, the collection's own is the one Astro ranks last (`[...path]` below
+ *   `[slug]`: a rest parameter ranks below a named one); every one ranked above it is
+ *   code that takes the documents' addresses first. So the trial's `[slug].astro` beside
+ *   `[...path].astro` at `/` is code: `validate` reports it as an error naming it and the
+ *   collection (`shadowingRoutes`), and it reserves its addresses like any other route
+ *   with parameters. A base's only route with parameters is always the collection's.
+ * - **Everything else is code.** A static route reserves exactly its URL; a route with
+ *   parameters reserves everything under its static prefix (and the prefix itself when
+ *   its first parameter is a rest parameter, which can be empty).
+ *
+ * The integration reads them once at setup (`site.codeRoutes`, so the editor's server and
+ * browser both have them); `validate` reads them from disk itself (cli/validate.ts). This
+ * module is pure and browser-safe: the reading of the folder is `code-routes-disk.ts`.
+ */
+
+/** An address compared with others: lower case, no trailing slash (slug.ts → sameAddress, kept here so slug.ts can import this). */
+const sameAddress = (url: string): string => {
+	const lower = url.toLowerCase();
+	return lower.length > 1 ? lower.replace(/\/+$/, '') : lower;
+};
+
+export interface CodeRoute {
+	/** The route's file, relative to the site's root, `/`-separated (`src/pages/about.astro`). */
+	file: string;
+	/** A static route's URL, or a route with parameters' static prefix, ending in `/` (`/work/`). */
+	url: string;
+	/** True for a route with parameters: it reserves everything under `url`. */
+	dynamic: boolean;
+	/** A dynamic route whose first parameter is a rest one (`[...path]`): it also matches `url` itself without its slash. */
+	rest: boolean;
+}
+
+/** The file extensions Astro routes from `src/pages/` (pages and endpoints). */
+export const ROUTE_EXTENSIONS = ['.astro', '.md', '.mdx', '.markdown', '.html', '.ts', '.js', '.mjs', '.mts'] as const;
+
+/**
+ * A file under the pages folder as its route, or null when it isn't one. `path` is the
+ * file's path inside the pages folder (`work/[slug].astro`); `file` is how to name it.
+ */
+export function routeOf(path: string, file: string): CodeRoute | null {
+	const parts = path.split('/').filter(Boolean);
+	if (parts.length === 0 || parts.some((p) => p.startsWith('_') || p.startsWith('.'))) return null;
+	const name = parts[parts.length - 1]!;
+	if (/\.d\.[mc]?ts$/.test(name)) return null;
+	const ext = ROUTE_EXTENSIONS.find((e) => name.endsWith(e));
+	if (!ext) return null;
+	const base = name.slice(0, -ext.length);
+	const segments = [...parts.slice(0, -1), ...(base === 'index' ? [] : [base])];
+	const firstParam = segments.findIndex((s) => s.includes('['));
+	if (firstParam === -1) return { file, url: `/${segments.join('/')}`, dynamic: false, rest: false };
+	const prefix = segments.slice(0, firstParam);
+	const url = prefix.length ? `/${prefix.join('/')}/` : '/';
+	return { file, url, dynamic: true, rest: /^\[\.\.\.[^\]]+\]$/.test(segments[firstParam]!) };
+}
+
+/**
+ * Astro's order for routes with parameters at the same static prefix, highest first: a
+ * named parameter above a rest one, more segments above fewer, then by name (Astro's own
+ * tie-break). Negative when `a` ranks above `b`.
+ */
+function astroRank(a: CodeRoute, b: CodeRoute): number {
+	if (a.rest !== b.rest) return a.rest ? 1 : -1;
+	const depth = (r: CodeRoute) => r.file.replace(/\/index\.[^/]+$/, '').split('/').length;
+	if (depth(a) !== depth(b)) return depth(b) - depth(a);
+	return a.file < b.file ? -1 : a.file > b.file ? 1 : 0;
+}
+
+/** A route with parameters at a collection's `urlBase` that isn't the collection's own: Astro ranks it above `own`, so it serves the documents' addresses first. */
+export interface ShadowingRoute<C> {
+	route: CodeRoute;
+	/** The collection's own route at that base (the one Astro ranks last). */
+	own: CodeRoute;
+	collection: C;
+}
+
+/** Every route with parameters that sits at a collection's base above the collection's own (see the header: one per base). */
+export function shadowingRoutes<C extends { urlBase: string | null }>(routes: readonly CodeRoute[], collections: readonly C[]): ShadowingRoute<C>[] {
+	const out: ShadowingRoute<C>[] = [];
+	const seen = new Set<string>();
+	for (const collection of collections) {
+		if (collection.urlBase === null) continue;
+		const base = sameAddress(collection.urlBase);
+		if (seen.has(base)) continue;
+		seen.add(base);
+		const at = routes.filter((r) => r.dynamic && sameAddress(r.url) === base).sort(astroRank);
+		const own = at[at.length - 1];
+		for (const route of at.slice(0, -1)) out.push({ route, own: own!, collection });
+	}
+	return out;
+}
+
+/** The routes that reserve URLs: every route but the collections' own (the last-ranked route with parameters at a collection's `urlBase`). */
+export function codeRoutesFrom(routes: readonly CodeRoute[], collections: readonly { urlBase: string | null }[]): CodeRoute[] {
+	const bases = new Set(collections.map((c) => c.urlBase).filter((b): b is string => b !== null).map((b) => sameAddress(b)));
+	const shadowing = new Set(shadowingRoutes(routes, collections).map((s) => s.route));
+	return routes.filter((r) => shadowing.has(r) || !(r.dynamic && bases.has(sameAddress(r.url))));
+}
+
+/** validate's sentence for a route that shadows a collection's documents. */
+export const shadowingMessage = (s: ShadowingRoute<{ name: string; urlBase: string | null }>): string =>
+	`${s.route.file} is a second route with parameters at the ${s.collection.name} collection's address (${s.collection.urlBase}), beside its own ${s.own.file}. Astro ranks it first, so it serves the addresses of that collection's documents and hides them. Move it under a folder of its own, or delete it if the documents replace it.`;
+
+/** The code route that serves `url` (a public address), or null. */
+export function codeRouteAt(url: string, routes: readonly CodeRoute[] | undefined): CodeRoute | null {
+	if (!routes?.length) return null;
+	const at = sameAddress(url);
+	// A static route first: it's the more specific (Astro's own priority).
+	const exact = routes.find((r) => !r.dynamic && sameAddress(r.url) === at);
+	if (exact) return exact;
+	return (
+		routes.find((r) => {
+			if (!r.dynamic) return false;
+			const prefix = r.url.toLowerCase();
+			if (prefix === '/') return at !== '/' || r.rest;
+			return at.startsWith(prefix) || (r.rest && at === sameAddress(prefix));
+		}) ?? null
+	);
+}
+
+/** The editor's and validate's sentence for a document at a code route's URL. */
+export const codeRouteMessage = (url: string, route: CodeRoute): string =>
+	`${url} is served by the site's own code (${route.file}), so a page can't go there.`;

package/src/columns.ts

@@ -0,0 +1,39 @@
+/**
+ * A collection's table columns (pre-M7 polish: a flat collection's documents as a
+ * table over the editor's stage). The config names them per collection (`columns`):
+ * its fields by key (a section builder's page fields too), of the kinds that show as one
+ * short value, and two built-ins. Posts and tags (Decision 13) add a reference, shown as
+ * the referenced document's title, and a list of references, its titles joined by commas.
+ * Shared by the config's check (config.ts) and the editor's table
+ * (editor/client/collections/table.ts), so the two agree on what a column can be.
+ */
+
+/** Built-in columns: the document's address, and when it was last edited. */
+export const BUILT_IN_COLUMNS = ['address', 'edited'] as const;
+export type BuiltInColumn = (typeof BUILT_IN_COLUMNS)[number];
+
+/** Without `columns`: the title (always first), the address and when it was last edited. */
+export const DEFAULT_COLUMNS: readonly BuiltInColumn[] = ['address', 'edited'];
+
+/** The field kinds a column can show. */
+export const COLUMN_FIELD_KINDS = ['text', 'select', 'toggle', 'date', 'number'] as const;
+
+/** What a column field can be, in words, for the config's refusals. */
+export const COLUMN_FIELD_WORDS = 'a text, select, toggle, date, number or reference field, or a list of references';
+
+/** A field's column kind: one of COLUMN_FIELD_KINDS, `reference`, `references` (a list of references), or null when it can't be a column. */
+export function columnKindOf(field: { kind: string; item?: { kind: string } | null }): (typeof COLUMN_FIELD_KINDS)[number] | 'reference' | 'references' | null {
+	if ((COLUMN_FIELD_KINDS as readonly string[]).includes(field.kind)) return field.kind as (typeof COLUMN_FIELD_KINDS)[number];
+	if (field.kind === 'reference') return 'reference';
+	if (field.kind === 'list' && field.item?.kind === 'reference') return 'references';
+	return null;
+}
+
+/** A collection's initial order (Decision 13): `title` or one of its columns, either way. */
+export interface SortConfig {
+	column: string;
+	order: 'asc' | 'desc';
+}
+
+export const isBuiltInColumn = (key: string): key is BuiltInColumn => (BUILT_IN_COLUMNS as readonly string[]).includes(key);
+export const isColumnField = (field: { kind: string; item?: { kind: string } | null }) => columnKindOf(field) !== null;

package/src/components/Block.astro

@@ -0,0 +1,46 @@
+---
+/**
+ * A block's root element. Use it as the outermost element of every block
+ * component; it adds the block's markers in preview renders (Decision 17) and
+ * nothing at all in the public render.
+ *
+ *   <Block cms={cms} as="section" class="hero">…</Block>
+ *
+ * Preview markers: `data-cms-block="<index>"` (the block's position in the
+ * document, the editor's index) and `data-cms-type="<type>"`. A click maps to its
+ * block with `el.closest('[data-cms-block]')`, and to its field with
+ * `el.closest('[data-cms-field]')`; a lockup's line set with `[data-cms-lines]`.
+ *
+ * M5a:
+ * - **A fields document's component** uses it as its root too (Decision 7): there it
+ *   carries `data-cms-document="<collection>"` in place of `data-cms-block` (Decision
+ *   16), and the fields' markers sit under it.
+ * - **A shared block on a page** (Decision 8) is never edited there, so its fields have
+ *   no markers; in a preview its root still carries `data-cms-block="<index>"`,
+ *   `data-cms-type` and `data-cms-shared="<name>"`, so the editor can outline and
+ *   select it.
+ */
+import type { HTMLTag } from 'astro/types';
+import type { BlockContext } from '../document.ts';
+import { passThrough } from './attributes.ts';
+
+interface Props {
+	cms: BlockContext;
+	as?: HTMLTag;
+	class?: string;
+	[attribute: string]: unknown;
+}
+
+const { cms, as: Tag = 'section', class: className, ...given } = Astro.props;
+// M8 trial (item 4): a bare attribute stays bare, false is none (attributes.ts).
+const rest = passThrough(given);
+const markers = cms.shared?.preview
+	? { 'data-cms-block': String(cms.index), 'data-cms-type': cms.type, 'data-cms-shared': cms.shared.name }
+	: !cms.preview
+		? {}
+		: cms.collection
+			? { 'data-cms-document': cms.collection }
+			: { 'data-cms-block': String(cms.index), 'data-cms-type': cms.type };
+---
+
+<Tag class={className} {...rest} {...markers}><slot /></Tag>

package/src/components/BlockRunTree.astro

@@ -0,0 +1,45 @@
+---
+/**
+ * `<Blocks>`'s own renderer for runs of blocks (M9 Decision 9; block-runs.ts): each entry
+ * as `<Blocks>` draws it (the block's component, or a skipped block's preview marker), and
+ * each run as its component round its own entries and runs, recursively. Internal: a site
+ * uses `<Blocks wrap={…}>`.
+ */
+import type { RunNode } from '../block-runs.ts';
+import type { BlockContext } from '../document.ts';
+import { skippedMarker } from '../skipped.ts';
+
+export interface RunItem {
+	Component: ((props: any) => any) | undefined;
+	data: Record<string, unknown> | null;
+	cms: BlockContext | null;
+	skipped: { type: string; shared?: string } | null;
+}
+
+interface Props {
+	nodes: RunNode[];
+	items: ReadonlyMap<number, RunItem>;
+	preview: boolean;
+}
+
+const { nodes, items, preview } = Astro.props;
+---
+
+{
+	nodes.map((node) => {
+		if (node.kind === 'run') {
+			const Wrapper = node.component as (props: any) => any;
+			return (
+				<Wrapper {...node.props}>
+					<Astro.self nodes={node.children} items={items} preview={preview} />
+				</Wrapper>
+			);
+		}
+		const item = items.get(node.index);
+		if (!item) return null;
+		const { Component, data, cms, skipped } = item;
+		if (Component && cms) return <Component block={data} cms={cms} />;
+		// As in Blocks.astro: a comment, so the site's sibling CSS matches across it.
+		return preview && skipped ? <Fragment set:html={skippedMarker(node.index, skipped)} /> : null;
+	})
+}

package/src/components/Blocks.astro

@@ -0,0 +1,139 @@
+---
+/**
+ * The page's body: put it where the page's content goes, `<Blocks document={document}
+ * collection={collection} preview={preview} />`. What it renders depends on the
+ * document's kind (M5a → Core framing):
+ *
+ * - **A section builder's** blocks, with the site's block components, in order.
+ * - **A list-of-fields document** (Decision 7) through its collection's component
+ *   (`collection` names it; the page component passes it on). The component gets
+ *   `{ document, cms }`: the document's render data plus its `title`, and a render
+ *   context whose `h1Field` is the first heading field in schema order with a value.
+ * - **A shared block on its own** (its own preview, Decision 8): the block alone,
+ *   following M3 Decision 16's `h1` rule as the page's only block.
+ *
+ * Rules, as before:
+ * - An unknown block type is skipped in the render (Decision 7; it stays in the file).
+ *   In a preview render only (Decision 17), it leaves an HTML comment where it would
+ *   be, `<!--cms-skipped <index> type=<type>-->` (skipped.ts),
+ *   so the editor can mark it (amber dashes, from the overlay layer) and open it. No
+ *   element: a site's sibling CSS matches across it, as on the public page, where
+ *   there's nothing for it at all.
+ * - **A shared-block entry** (`{ "shared": "footer" }`, Decision 8) renders the shared
+ *   block as it stands in the page's own source (Decision 9: the disk at build, the
+ *   editor's store in a preview). One that names a shared block that doesn't exist,
+ *   or whose type the code doesn't know, is skipped exactly as an unknown block is
+ *   (its comment also says `shared=<name>`).
+ * - A document with no blocks leaves, in a preview render only, an empty area
+ *   (`data-cms-empty`) where its blocks would go, so the editor can offer "Add the
+ *   first block" on the page (Phase 4's insert points). The public render has nothing.
+ * - Each block gets `{ block, cms }`: its render data (fields.ts → renderData: the
+ *   parsed data, with a value the field can't use, such as a number out of range,
+ *   as `null`, M5a Decision 15; a reference to a document that doesn't exist as
+ *   `null`, Decision 6), and its render context (document.ts → BlockContext): its
+ *   index, whether this is a preview render (Decision 17), which of its fields holds
+ *   the page's `h1` (Decision 16), `read`, the other documents (Decision 9), and
+ *   `listPage`, the page of a paged listing (posts and tags, Decision 12: the page
+ *   component passes on the `listPage` it gets, 1 when it doesn't).
+ * - The context is computed here, per render, and passed down as props: no module
+ *   state, so concurrent preview renders can't leak into each other.
+ * - **Runs of blocks** (M9 Decision 9): `wrap` is the page component's rule for which
+ *   neighbouring blocks go together and what's drawn round them (a band of cards, each
+ *   card several blocks). It gets the blocks that render (`{ index, type, data }`) and
+ *   returns runs, `{ from, to, component, props?, runs? }` (block-runs.ts). Each block in a
+ *   run keeps its index, context, markers, selection and morph, exactly as outside one.
+ *   A section builder's (or a shared block's) blocks only.
+ */
+import { blocks } from 'virtual:caracms/blocks';
+import { components } from 'virtual:caracms/collections';
+import { site } from 'virtual:caracms/config';
+import { blockContexts, documentKind, fieldsHeading, own, type BlockContext, type DocumentBlock, type PageDocument, type SiteDocument } from '../document.ts';
+import { firstImagePath } from '../fields.ts';
+import { documentReader, renderFields, renderSourceOf, resolveShared } from '../read.ts';
+import { skippedMarker } from '../skipped.ts';
+import { runTree, type RunNode, type WrapBlocks } from '../block-runs.ts';
+import BlockRunTree from './BlockRunTree.astro';
+
+interface Props {
+	document: PageDocument;
+	/** The document's collection: needed for a fields document (its component is the collection's). */
+	collection?: string;
+	preview?: boolean;
+	/** Posts and tags, Decision 12: the page of a paged listing (the page component's `listPage`); 1 by default. */
+	listPage?: number;
+	/** M9 Decision 9: which runs of blocks go together, and what's drawn round each (block-runs.ts). */
+	wrap?: WrapBlocks;
+}
+
+const { document, collection, preview = false, wrap } = Astro.props;
+// 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;
+const read = documentReader(site, renderSourceOf(Astro.locals));
+const kind = documentKind(document);
+
+interface Item {
+	index: number;
+	Component: ((props: any) => any) | undefined;
+	data: Record<string, unknown> | null;
+	cms: BlockContext | null;
+	skipped: { type: string; shared?: string } | null;
+}
+let items: Item[] = [];
+let empty = false;
+let body: { Component: (props: any) => any; props: Record<string, unknown> } | null = null;
+let tree: RunNode[] | null = null;
+
+if (kind === 'fields') {
+	const c = collection ? own(site.collections, collection) : undefined;
+	if (!c || c.kind !== 'fields') throw new Error(`<Blocks>: a list-of-fields document needs its collection (pass collection={collection}); got ${JSON.stringify(collection)}.`);
+	const Component = components[c.name];
+	if (!Component) throw new Error(`<Blocks>: collection "${c.name}" has no component.`);
+	const doc = document as Extract<PageDocument, { kind: 'fields' }>;
+	const fields = c.fields ?? {};
+	// M5b Decision 4: a fields document is its page's first block, so its images load eagerly and its first (the cover) is high priority.
+	const cms: BlockContext = { index: 0, first: true, type: c.name, preview, h1Field: fieldsHeading(fields, doc.data), collection: c.name, shared: null, read, listPage, eager: true, priority: firstImagePath(fields, doc.data) };
+	body = { Component, props: { document: { ...(await renderFields(fields, doc.data, read)), title: doc.title }, cms } };
+} else {
+	// A shared block on its own renders as the only block of a page (Decision 8).
+	const page: SiteDocument = kind === 'shared' ? { title: document.title, blocks: [(document as Extract<PageDocument, { kind: 'shared' }>).block] } : (document as SiteDocument);
+	const resolved = new Map<number, DocumentBlock>();
+	const skips = new Map<number, { type: string; shared: string }>();
+	await Promise.all(
+		page.blocks.map(async (entry, i) => {
+			if (entry.shared === undefined) return;
+			const r = await resolveShared(entry, read);
+			if ('block' in r) resolved.set(i, r.block);
+			else skips.set(i, { type: r.type, shared: entry.shared });
+		}),
+	);
+	const contexts = blockContexts(page, site, preview, read, resolved, listPage);
+	items = await Promise.all(
+		page.blocks.map(async (entry, i): Promise<Item> => {
+			const cms = contexts[i] ?? null;
+			const block = resolved.get(i) ?? entry;
+			const Component = cms ? blocks[block.type] : undefined;
+			if (Component && cms) return { index: i, Component, data: await renderFields(own(site.blocks, block.type)!.fields, block.data, read), cms, skipped: null };
+			return { index: i, Component: undefined, data: null, cms: null, skipped: skips.get(i) ?? { type: entry.type } };
+		}),
+	);
+	empty = page.blocks.length === 0;
+	if (wrap) {
+		const rendered = items.filter((it) => it.Component && it.cms).map((it) => ({ index: it.index, type: it.cms!.type, data: it.data! }));
+		const runs = wrap(rendered);
+		if (runs.length) tree = runTree(items.map((it) => it.index), runs);
+	}
+}
+const byIndex = new Map(items.map((it) => [it.index, it]));
+---
+
+{body && <body.Component {...body.props} />}
+{tree && <BlockRunTree nodes={tree} items={byIndex} preview={preview} />}
+{
+	!tree &&
+	items.map(({ index, Component, data, cms, skipped }) => {
+		if (Component && cms) return <Component block={data} cms={cms} />;
+		// A comment, not an element: the site's sibling CSS (`+`, `:has(+ …)`) matches across it as on the public page.
+		return preview && skipped ? <Fragment set:html={skippedMarker(index, skipped)} /> : null;
+	})
+}
+{preview && empty ? <div data-cms-empty="" aria-hidden="true" style="display:block;min-height:320px;margin:0;padding:0;border:0" /> : null}

package/src/components/Buttons.astro

@@ -0,0 +1,116 @@
+---
+/**
+ * A buttons field (M5a Decision 2; the template's one button shape):
+ * `[{ label, href, style }]` as links. A block author never writes the "half a
+ * button shows nothing" rule: this component applies it.
+ *
+ *   <Buttons cms={cms} field="buttons" value={block.buttons} class="actions" buttonClass="button" />
+ *
+ * - Shows the first `max` buttons (the field's, default 2) that have both a label
+ *   and an href passing the link rule. Half a button, or one whose link fails the
+ *   rule, shows nothing (the field says why). Indexes stay the field's own, so
+ *   markers line up with the editor's rows.
+ * - Each is `<a href class="<buttonClass> <buttonClass>--<style>">label</a>`, in a
+ *   wrapper element `as` (default `div`) that takes `class` and other attributes.
+ *   Public render: nothing at all when no button shows.
+ * - A field with `allowNoLink` (the editor-friction batch, item 4): a button with words
+ *   and no link is meant ("Coming soon"), and shows as a plain label with the same
+ *   classes, `<span class="<buttonClass> <buttonClass>--<style>">label</span>`. A
+ *   custom slot gets it with `href: ''` and `linked: false`. One whose link fails the
+ *   rule still shows nothing (the field says why).
+ * - Or render each one yourself with a function as the default slot:
+ *     <Buttons cms={cms} field="buttons" value={block.buttons}>
+ *       {(b) => <a href={b.href} class={`btn btn-${b.style}`} {...b.markers}>{b.label}</a>}
+ *     </Buttons>
+ *   `b` is `{ label, href, linked, style, index, markers }`; spread `markers` on the element.
+ * - Preview render only (M3 Decision 17): the wrapper is always there with
+ *   `data-cms-field="<path>" data-cms-kind="buttons"`, and each button carries
+ *   `data-cms-field="<path>.<index>.label" data-cms-kind="button"` (Decision 16).
+ * - M6c Decision 11: a button whose link is a file link carries the site's behaviour
+ *   (`fileLinkAttributes`): `target="_blank" rel="noopener"` and a visually hidden
+ *   " (opens in a new tab)" for a PDF without `?download`, `download` for any other.
+ *   A custom slot gets them as `b.attributes` (spread them) and `b.newTabNote` (HTML
+ *   to put inside, or '').
+ */
+import { site } from 'virtual:caracms/config';
+import type { HTMLTag } from 'astro/types';
+import type { BlockContext } from '../document.ts';
+import { parseField, usableHref, type ButtonValue } from '../fields.ts';
+import { fileLinkAttributes, NEW_TAB_NOTE_HTML } from '../rich-text.ts';
+import { requireField } from './descriptor.ts';
+import { passThrough } from './attributes.ts';
+
+/** One button as the default slot's function gets it. */
+export interface ShownButton {
+	label: string;
+	/** Where it goes; '' for a plain label (a field with `allowNoLink`, a button with no link). */
+	href: string;
+	/** False for a plain label: draw it as text with the button's look, not a link. */
+	linked: boolean;
+	style: string;
+	/** Its index in the field's value (the editor's row). */
+	index: number;
+	/** The preview markers to spread on its element (empty in the public render). */
+	markers: Record<string, string>;
+	/** A file link's attributes to spread on its element (M6c Decision 11), else empty. */
+	attributes: Record<string, string | boolean>;
+	/** The visually hidden " (opens in a new tab)" to put inside a new-tab file link, else ''. */
+	newTabNote: string;
+}
+
+interface Props {
+	cms: BlockContext;
+	field: string;
+	value: ButtonValue[];
+	as?: HTMLTag;
+	class?: string;
+	/** Each button's class, and `<buttonClass>--<style>` beside it. */
+	buttonClass?: string;
+	[attribute: string]: unknown;
+}
+
+const { cms, field, value, as: Tag = 'div', class: className, buttonClass, ...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, 'buttons', 'Buttons');
+const all = parseField(descriptor, value) as ButtonValue[];
+const shown: ShownButton[] = [];
+all.slice(0, descriptor.max).forEach((b, index) => {
+	if (!b.label) return;
+	const markers: Record<string, string> = cms.preview ? { 'data-cms-field': `${field}.${index}.label`, 'data-cms-kind': 'button' } : {};
+	// allowNoLink: words and no link at all are a plain label.
+	if (!b.href && descriptor.allowNoLink) {
+		shown.push({ label: b.label, href: '', linked: false, style: b.style, index, markers, attributes: {}, newTabNote: '' });
+		return;
+	}
+	const href = usableHref(b.href);
+	if (!href) return;
+	const file = fileLinkAttributes(href);
+	const attributes = Object.fromEntries(Object.entries(file.attributes).map(([name, v]) => [name, v === '' ? true : v]));
+	shown.push({ label: b.label, href, linked: true, style: b.style, index, markers, attributes, newTabNote: file.newTab ? NEW_TAB_NOTE_HTML : '' });
+});
+const custom = Astro.slots.has('default');
+const rendered = custom ? await Promise.all(shown.map((b) => Astro.slots.render('default', [b]))) : [];
+const markers = cms.preview ? { 'data-cms-field': field, 'data-cms-kind': 'buttons' } : {};
+---
+
+{
+	(shown.length > 0 || cms.preview) && (
+		<Tag class={className} {...rest} {...markers}>
+			{custom
+				? rendered.map((html) => <Fragment set:html={html} />)
+				: shown.map((b) =>
+						b.linked ? (
+							<a href={b.href} class:list={buttonClass ? [buttonClass, `${buttonClass}--${b.style}`] : undefined} {...b.attributes} {...b.markers}>
+								{b.label}
+								{b.newTabNote && <Fragment set:html={b.newTabNote} />}
+							</a>
+						) : (
+							<span class:list={buttonClass ? [buttonClass, `${buttonClass}--${b.style}`] : undefined} {...b.markers}>
+								{b.label}
+							</span>
+						),
+					)}
+		</Tag>
+	)
+}

package/src/components/Fonts.astro

@@ -0,0 +1,14 @@
+---
+/**
+ * The text styles' fonts, for the page's `<head>`: `<Fonts />`. Astro's fonts API
+ * emits each `@font-face` (registered by the integration from the text styles,
+ * `font-display: block`, Decision 14) and a preload.
+ */
+import { Font } from 'astro:assets';
+import { site } from 'virtual:caracms/config';
+
+const styles = Object.values(site.textStyles);
+const variables = [...new Set(styles.map((s) => s.cssVariable))];
+---
+
+{variables.map((cssVariable) => <Font cssVariable={cssVariable as any} preload />)}