caracms 0.0.0-stage → 0.2.0

package/src/block-runs.ts

@@ -0,0 +1,84 @@
+/**
+ * Runs of blocks (M9 Decision 9): the page component tells `<Blocks>` which neighbouring
+ * blocks go together and what's drawn round them, such as a band holding cards, each card
+ * holding several blocks (a Tina template's About page).
+ *
+ *   <Blocks document={document} collection={collection} preview={preview} wrap={cardRuns} />
+ *
+ *   // The page component's own rule, from the blocks' data:
+ *   const cardRuns: WrapBlocks = (blocks) => …[{ from: 2, to: 6, component: Band, runs: [
+ *     { from: 2, to: 4, component: Card, props: { id: 'story' } },
+ *     { from: 5, to: 6, component: Card, props: { id: 'team' } },
+ *   ] }];
+ *
+ * - `wrap` gets the blocks that render, in order: each one's document index, type and render
+ *   data (what its component gets as `block`), so the rule can read a field (`card`, `anchor`).
+ * - A run is `from`..`to`, document indices, inclusive: everything between renders inside it,
+ *   a skipped block's preview marker included. Its `component` is drawn round the run with
+ *   `props`, the blocks in its default slot. `runs` are runs inside it (the cards in a band),
+ *   each within it.
+ * - Runs are in order and don't overlap. A rule that breaks that is a mistake in the site's
+ *   code, so the render stops with a sentence saying which runs.
+ * - Nothing about each block changes: its index, its context (`index`, `first`, `h1Field`,
+ *   `eager`), its markers in a preview, so it's selected, typed into and morphed there as
+ *   anywhere else. A wrapper carries no markers: it's the site's markup.
+ */
+
+/** A block as `wrap` sees it. */
+export interface WrapBlock {
+	/** Its index in the document (the editor's index, `cms.index`). */
+	index: number;
+	type: string;
+	/** Its render data: what its component gets as `block`. */
+	data: Record<string, unknown>;
+}
+
+/** A run of blocks and what's drawn round it. */
+export interface BlockRun {
+	/** The first block's document index. */
+	from: number;
+	/** The last block's document index (inclusive). */
+	to: number;
+	/** An Astro component (or any component Astro renders): the run goes in its default slot. */
+	component: unknown;
+	props?: Record<string, unknown>;
+	/** Runs inside this one, each within `from`..`to`. */
+	runs?: readonly BlockRun[];
+}
+
+/** The page component's rule: the runs, from the blocks that render. */
+export type WrapBlocks = (blocks: readonly WrapBlock[]) => readonly BlockRun[];
+
+/** What `<Blocks>` draws, as a tree: an entry (by document index), or a run holding more. */
+export type RunNode = { kind: 'entry'; index: number } | { kind: 'run'; component: unknown; props: Record<string, unknown>; children: RunNode[] };
+
+const named = (run: BlockRun) => `the run ${run.from}–${run.to}`;
+
+/**
+ * The document's entries (`indices`, in order: every block the render has an entry for)
+ * grouped by `runs`. Throws on runs out of order, overlapping, outside their parent, or
+ * with `from` after `to`.
+ */
+export function runTree(indices: readonly number[], runs: readonly BlockRun[]): RunNode[] {
+	const place = (within: readonly number[], level: readonly BlockRun[], parent: BlockRun | null): RunNode[] => {
+		let previous: BlockRun | null = null;
+		for (const run of level) {
+			if (!Number.isInteger(run.from) || !Number.isInteger(run.to) || run.from > run.to) throw new Error(`<Blocks wrap>: ${named(run)} needs whole-number indices with from at or before to.`);
+			if (!run.component) throw new Error(`<Blocks wrap>: ${named(run)} has no component to draw round it.`);
+			if (previous && run.from <= previous.to) throw new Error(`<Blocks wrap>: ${named(run)} starts before ${named(previous)} ends. Runs are in document order and don't overlap.`);
+			if (parent && (run.from < parent.from || run.to > parent.to)) throw new Error(`<Blocks wrap>: ${named(run)} isn't inside ${named(parent)}, which holds it.`);
+			previous = run;
+		}
+		const out: RunNode[] = [];
+		let i = 0;
+		for (const run of level) {
+			while (i < within.length && within[i]! < run.from) out.push({ kind: 'entry', index: within[i++]! });
+			const inside: number[] = [];
+			while (i < within.length && within[i]! <= run.to) inside.push(within[i++]!);
+			out.push({ kind: 'run', component: run.component, props: run.props ?? {}, children: place(inside, run.runs ?? [], run) });
+		}
+		while (i < within.length) out.push({ kind: 'entry', index: within[i++]! });
+		return out;
+	};
+	return place(indices, runs, null);
+}

package/src/cards.ts

@@ -0,0 +1,158 @@
+/**
+ * M6c (G5): the grid view of a flat collection, package side. Pure, so the config's
+ * check (config.ts), the listing (content.ts) and the editor share one reading.
+ *
+ * - **Which collections get the switch** (Decision 13): a flat collection whose
+ *   documents can hold an image. A fields collection with a media field anywhere in its
+ *   fields (lists included); a section builder when any of the site's blocks, or its own
+ *   page fields, has one. Never Pages (nested), Shared blocks or Site Settings.
+ * - **A card's picture** (Decision 14): the document's first image. A fields document:
+ *   the first in schema order, or the field `view.image` names (a list of media gives its
+ *   first item). A section builder's: its page fields first, then each block in order,
+ *   shared entries and unknown blocks skipped. A clip (a loop too) stands as its poster.
+ * - **The config** (Decision 17): `view: { default?, image?, ratio? }`; defaults list, the
+ *   first image, 4:3.
+ */
+import { firstMedia, holdsMedia, type Fields } from './fields.ts';
+import { parseMedia, renderMedia, type RenderMedia } from './media-value.ts';
+import type { DocumentBlock } from './document.ts';
+
+export const VIEW_MODES = ['list', 'grid'] as const;
+export type ViewMode = (typeof VIEW_MODES)[number];
+
+/** A card's picture ratios, as the config writes them. */
+export const CARD_RATIOS = ['4:3', '3:2', '1:1', '16:9', '3:4'] as const;
+export type CardRatio = (typeof CARD_RATIOS)[number];
+
+/** `view` in a collection's config (Decision 17). */
+export interface ViewConfig {
+	/** The view a collection opens in until an editor picks one (then the editor's own choice, Decision 18). Default `'list'`. */
+	default?: ViewMode;
+	/** A fields collection only: the top-level media field (or list of media) a card shows. Default: the first image. */
+	image?: string;
+	/** The card's picture ratio. Default `'4:3'`. */
+	ratio?: CardRatio;
+}
+
+/** A collection's view, checked and defaulted; on a collection only when it gets the switch. */
+export interface ResolvedView {
+	default: ViewMode;
+	image: string | null;
+	ratio: CardRatio;
+}
+
+export const defaultResolvedView = (): ResolvedView => ({ default: 'list', image: null, ratio: '4:3' });
+
+/** `'4:3'` → 4 / 3. */
+export function ratioValue(ratio: CardRatio): number {
+	const [w, h] = ratio.split(':').map(Number);
+	return w! / h!;
+}
+
+/** Can a flat collection's documents hold an image (Decision 13)? `blocks`: every block's fields (a section builder can take any of them). */
+export function collectionHoldsImages(collection: { kind: string; nested: boolean; fields: Fields | null }, blocks: Iterable<{ fields: Fields }>): boolean {
+	if (collection.nested) return false;
+	if (collection.kind === 'fields') return holdsMedia(collection.fields);
+	if (collection.kind !== 'sections') return false;
+	if (holdsMedia(collection.fields)) return true;
+	for (const b of blocks) if (holdsMedia(b.fields)) return true;
+	return false;
+}
+
+/** A card's picture before it's signed: an image's key, alt and focal point, or a clip's poster. */
+export type CardCover =
+	| { kind: 'image'; key: string; alt: string; focal: [number, number] | null }
+	| { kind: 'clip'; playbackId: string; time: number | null; duration: number | null; name: string };
+
+function coverOf(value: unknown, media: RenderMedia): CardCover {
+	if (media.kind === 'image') return { kind: 'image', key: media.key, alt: media.alt, focal: media.focal };
+	const stored = parseMedia(value);
+	const time = stored && 'video' in stored && typeof stored.poster === 'number' ? stored.poster : null;
+	return { kind: 'clip', playbackId: media.playbackId, time, duration: media.duration, name: media.name };
+}
+
+/** A fields document's cover: `view.image`'s field when named, else the first image in schema order. */
+export function fieldsCover(fields: Fields, data: Record<string, unknown>, image: string | null): CardCover | null {
+	if (image !== null) {
+		const field = fields[image];
+		if (field?.kind === 'media') {
+			const media = renderMedia(data[image], { only: field.only, play: field.play });
+			return media ? coverOf(data[image], media) : null;
+		}
+		if (field?.kind === 'list' && field.item?.kind === 'media' && Array.isArray(data[image])) {
+			const item = field.item;
+			for (const v of data[image] as unknown[]) {
+				const media = renderMedia(v, { only: item.only, play: item.play });
+				if (media) return coverOf(v, media);
+			}
+		}
+		return null;
+	}
+	const found = firstMedia(fields, data);
+	return found ? coverOf(found.value, found.media) : null;
+}
+
+/** A section builder's document's cover: its page fields' first image, then each block's in order (shared entries and unknown blocks skipped). */
+export function sectionsCover(pageFields: Fields | null, data: Record<string, unknown> | undefined, blocks: readonly DocumentBlock[], schemas: Record<string, { fields: Fields }>): CardCover | null {
+	if (pageFields && data) {
+		const found = firstMedia(pageFields, data);
+		if (found) return coverOf(found.value, found.media);
+	}
+	for (const block of blocks) {
+		if (block.shared !== undefined || !block.known) continue;
+		const schema = schemas[block.type];
+		if (!schema) continue;
+		const found = firstMedia(schema.fields, block.data);
+		if (found) return coverOf(found.value, found.media);
+	}
+	return null;
+}
+
+/**
+ * `view` from a collection's config, checked (Decision 17): null when the collection
+ * gets no switch (and then `view` is refused if set, with a sentence); else the
+ * defaulted view. `fields` is the collection's (a fields collection's, or a section
+ * builder's page fields).
+ */
+export function checkView(
+	where: string,
+	raw: unknown,
+	collection: { kind: 'fields' | 'sections'; nested: boolean; fields: Fields | null },
+	blocks: Iterable<{ fields: Fields }>,
+	fail: (message: string) => never,
+): ResolvedView | null {
+	const switches = collectionHoldsImages(collection, blocks);
+	if (raw === undefined) return switches ? defaultResolvedView() : null;
+	if (collection.nested) fail(`${where}: view is for a flat collection's List / Grid switch; a nested one (Pages) is a tree.`);
+	if (!switches) {
+		fail(
+			collection.kind === 'fields'
+				? `${where}: view: its documents have no media field, so there's nothing to show as a grid. Add a media() field, or take view out.`
+				: `${where}: view: none of the blocks it offers has a media field, so there's nothing to show as a grid. Take view out.`,
+		);
+	}
+	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail(`${where}: view must be an object, like { default: 'grid', ratio: '3:2' }.`);
+	const v = raw as Record<string, unknown>;
+	for (const key of Object.keys(v)) {
+		if (key !== 'default' && key !== 'image' && key !== 'ratio') fail(`${where}: view has no "${key}"; it takes default, image and ratio.`);
+	}
+	const view = defaultResolvedView();
+	if (v.default !== undefined) {
+		if (!(VIEW_MODES as readonly unknown[]).includes(v.default)) fail(`${where}: view.default must be 'list' or 'grid' (got ${JSON.stringify(v.default)}).`);
+		view.default = v.default as ViewMode;
+	}
+	if (v.ratio !== undefined) {
+		if (!(CARD_RATIOS as readonly unknown[]).includes(v.ratio)) fail(`${where}: view.ratio must be one of ${CARD_RATIOS.map((r) => `'${r}'`).join(', ')} (got ${JSON.stringify(v.ratio)}).`);
+		view.ratio = v.ratio as CardRatio;
+	}
+	if (v.image !== undefined) {
+		if (collection.kind !== 'fields') fail(`${where}: view.image is for a list-of-fields collection; a section builder's card shows the first image in its page fields or blocks.`);
+		if (typeof v.image !== 'string' || v.image === '') fail(`${where}: view.image must name one of its media fields (got ${JSON.stringify(v.image)}).`);
+		const field = collection.fields?.[v.image];
+		if (!field) fail(`${where}: view.image: "${v.image}" isn't one of its fields; name a media field, or a list of media.`);
+		const isMedia = field.kind === 'media' || (field.kind === 'list' && field.item?.kind === 'media');
+		if (!isMedia) fail(`${where}: view.image: "${v.image}" is a ${field.kind === 'list' ? 'list of fields' : `${field.kind} field`}; a card's picture comes from a media field, or a list of media (its first item).`);
+		view.image = v.image;
+	}
+	return view;
+}

package/src/cli/schemas.ts

@@ -0,0 +1,122 @@
+/**
+ * `caracms schemas` (M8 Decision 14): write `schemas/` from the config, and give every
+ * content file that lacks one its `$schema` key (or correct a wrong path). `init` and
+ * `validate --fix` run it; `astro dev` runs only the first half (`writeSchemaFiles`), so a
+ * dev run never touches content.
+ *
+ * `schemas/` is the package's: a `*.schema.json` there that the config no longer makes
+ * (a collection removed or renamed) is deleted. Nothing else in it is touched.
+ */
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ResolvedSite } from '../config.ts';
+import { siteSchemas, schemaText } from '../content-schema.ts';
+import { listDocuments } from '../content.ts';
+import { SCHEMAS_FOLDER, schemaRef, stampSchema } from '../schema-key.ts';
+import { loadSite } from './site.ts';
+
+// `caracms init` loads the site through this module too (bin/init.mjs).
+export { loadSite };
+
+type Site = Pick<ResolvedSite, 'root' | 'blocks' | 'collections'>;
+
+export interface SchemaFileChange {
+	/** Site-relative. */
+	file: string;
+	/** Null: the file goes (the config no longer makes it). */
+	text: string | null;
+	/** What's there now; null when it's new. */
+	before: string | null;
+}
+
+const read = (path: string): string | null => {
+	try {
+		return readFileSync(path, 'utf8');
+	} catch {
+		return null;
+	}
+};
+
+/** The schema files that differ from what the config makes: new, changed or gone. Empty when they're current. */
+export function schemaFileChanges(site: Site): SchemaFileChange[] {
+	const out: SchemaFileChange[] = [];
+	const made = siteSchemas(site);
+	for (const [name, schema] of made) {
+		const file = `${SCHEMAS_FOLDER}/${name}`;
+		const text = schemaText(schema);
+		const before = read(join(site.root, file));
+		if (before !== text) out.push({ file, text, before });
+	}
+	let names: string[] = [];
+	try {
+		names = readdirSync(join(site.root, SCHEMAS_FOLDER));
+	} catch {
+		// No folder yet.
+	}
+	for (const name of names.sort()) {
+		if (!name.endsWith('.schema.json') || made.has(name)) continue;
+		const file = `${SCHEMAS_FOLDER}/${name}`;
+		out.push({ file, text: null, before: read(join(site.root, file)) });
+	}
+	return out;
+}
+
+/** Write the schema files (astro dev's half). Returns what changed. */
+export function writeSchemaFiles(site: Site): SchemaFileChange[] {
+	const changes = schemaFileChanges(site);
+	if (changes.length) mkdirSync(join(site.root, SCHEMAS_FOLDER), { recursive: true });
+	for (const c of changes) {
+		const path = join(site.root, c.file);
+		if (c.text === null) rmSync(path, { force: true });
+		else writeFileSync(path, c.text);
+	}
+	return changes;
+}
+
+export interface StampChange {
+	file: string;
+	text: string;
+	before: string;
+}
+
+/** Content files whose `$schema` is missing or wrong, with their stamped text. A file that isn't JSON is left alone. */
+export async function stampChanges(site: Site): Promise<StampChange[]> {
+	const out: StampChange[] = [];
+	for (const entry of await listDocuments(site)) {
+		const before = read(join(site.root, entry.file));
+		if (before === null) continue;
+		const text = stampSchema(before, schemaRef(site.collections[entry.collection]!, entry.file));
+		if (text !== before) out.push({ file: entry.file, text, before });
+	}
+	return out;
+}
+
+export interface SchemasResult {
+	/** Schema files written or removed. */
+	schemas: SchemaFileChange[];
+	/** Content files given their `$schema`. */
+	stamped: string[];
+}
+
+/** The whole command, on a resolved site. */
+export async function runSchemas(site: Site): Promise<SchemasResult> {
+	const schemas = writeSchemaFiles(site);
+	const stamps = await stampChanges(site);
+	for (const s of stamps) writeFileSync(join(site.root, s.file), s.text);
+	return { schemas, stamped: stamps.map((s) => s.file) };
+}
+
+/** What `caracms schemas` prints for a result. */
+export function schemasReport(result: SchemasResult): string {
+	if (!result.schemas.length && !result.stamped.length) return 'caracms schemas: the schemas and every content file\'s $schema are up to date.\n';
+	const lines: string[] = [];
+	for (const c of result.schemas) lines.push(`  ${c.text === null ? 'removed' : 'wrote'} ${c.file}`);
+	for (const f of result.stamped) lines.push(`  added $schema to ${f}`);
+	return `caracms schemas:\n${lines.join('\n')}\n`;
+}
+
+/** The command's entry (bin/caracms.mjs loads this module through the site's Vite). */
+export async function command(root: string): Promise<{ code: number; out: string }> {
+	const result = await runSchemas(await loadSite(root));
+	return { code: 0, out: schemasReport(result) };
+}

package/src/cli/site.ts

@@ -0,0 +1,66 @@
+/**
+ * The site as the commands see it (M8): its `caracms.config.ts`, loaded and resolved as
+ * the integration resolves it, and its content files on disk. Loaded through the site's
+ * own Vite (bin/site-runner.mjs), so the config's TypeScript and its imports of
+ * `caracms/config` work on any Node the package supports.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { resolveSite, type ResolvedSite, type SiteConfig } from '../config.ts';
+
+/** The config file names a site may use, in the order they're looked for. */
+export const CONFIG_FILES = ['caracms.config.ts', 'caracms.config.mts', 'caracms.config.mjs', 'caracms.config.js'] as const;
+
+export class CommandError extends Error {}
+
+export function configFile(root: string): string | null {
+	for (const name of CONFIG_FILES) if (existsSync(join(root, name))) return name;
+	return null;
+}
+
+/** The site's resolved config. Throws a CommandError with the config's own sentence when it's missing or wrong. */
+export async function loadSite(root: string): Promise<ResolvedSite> {
+	const name = configFile(root);
+	if (!name) throw new CommandError(`there's no caracms.config.ts in ${root}. Run this from the site's root (run \`caracms init\` first on a site without caracms).`);
+	let config: SiteConfig;
+	try {
+		config = ((await import(/* @vite-ignore */ join(root, name))) as { default: SiteConfig }).default;
+	} catch (error) {
+		throw new CommandError(`${name} couldn't be loaded: ${(error as Error).message}`);
+	}
+	if (!config || typeof config !== 'object') throw new CommandError(`${name} has no default export. It should end \`export default defineSite({ … })\`.`);
+	try {
+		return resolveSite(config, root);
+	} catch (error) {
+		throw new CommandError((error as Error).message);
+	}
+}
+
+export const posix = (path: string): string => path.split(sep).join('/');
+
+/** Every `.json` file under `dir` (absolute), site-relative and `/`-separated; dot folders and files skipped. */
+export function jsonFilesUnder(root: string, dir: string): string[] {
+	const out: string[] = [];
+	const walk = (d: string) => {
+		let names: string[];
+		try {
+			names = readdirSync(d);
+		} catch {
+			return;
+		}
+		for (const n of names.sort()) {
+			if (n.startsWith('.')) continue;
+			const p = join(d, n);
+			let isDir = false;
+			try {
+				isDir = statSync(p).isDirectory();
+			} catch {
+				continue;
+			}
+			if (isDir) walk(p);
+			else if (n.endsWith('.json')) out.push(posix(relative(root, p)));
+		}
+	};
+	walk(dir);
+	return out;
+}