caracms 0.0.0-stage → 0.2.0

package/src/editor/client/fields/SeoGroup.tsx

@@ -0,0 +1,282 @@
+/**
+ * Search and sharing (M6 Decision 13; the mockup's #seo-page, #seo-long, #seo-defaults,
+ * #seo-case): a document's own `seo` key, as one collapsed group that says what's set.
+ * At the foot of a section-builder page's block list (below Add block), and at the end of
+ * a fields document's form. Only on collections with a URL.
+ *
+ * - **Search title** and **Search description**: plain text with M5a's count and M6's
+ *   soft limits (60 and 160, seo.ts). Over the limit the count and a note turn amber, and
+ *   nothing is blocked.
+ * - **Share image**: an image-only media slot with **no alt input** (like the brand's
+ *   logo, M5b Decision 11) that may have a focal point; never in Publish's alt summary.
+ * - Blank parts fall back to Site Settings' defaults (the placeholders say what).
+ *
+ * The values live in the document store beside the blocks (`SEO_SCOPE`, document-store.ts):
+ * clearing the last part removes `seo` from the file, and a file with none is untouched.
+ *
+ * `SoftText` is also Site Settings' (its Search and sharing defaults).
+ */
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
+import { media as mediaField } from '../../../fields.ts';
+import { parseMedia } from '../../../media-value.ts';
+import { SETTINGS_PATH } from '../../../reserved.ts';
+import { SEO_DESCRIPTION_SOFT_LIMIT, SEO_TITLE_SOFT_LIMIT } from '../../../seo.ts';
+import { ENDPOINTS, sameDoc, type AnyOpenedDocument } from '../../types.ts';
+import { useEditor, useStore } from '../context.tsx';
+import type { Editor, View } from '../editor.ts';
+import { Icon } from '../shell/Icons.tsx';
+import { SEO_SCOPE } from '../state/document-store.ts';
+import { createStore, type Store } from '../state/store.ts';
+import { FieldFrame } from './FieldFrame.tsx';
+import { FieldHostProvider, parseBase, useHost, type FieldHost } from './host.tsx';
+import { MediaSlot } from './MediaField.tsx';
+
+const TITLE_WHY = 'search results usually cut a title off around here';
+const DESC_WHY = 'search results usually cut a description off around here';
+const SHARE_IMAGE = mediaField({ only: 'image' });
+
+/**
+ * A text field with a count and a soft limit (M6 Decision 13, Decision 17's intro): over
+ * `max`, the count and a note turn amber; nothing is blocked.
+ */
+export function SoftText(props: {
+	scope: string;
+	name: string;
+	label: string;
+	value: string;
+	max: number;
+	multiline?: boolean;
+	placeholder?: string;
+	help?: ReactNode;
+	overWhy?: string;
+	disabled?: boolean;
+	onChange: (value: string) => void;
+}) {
+	const id = `f-${props.scope}-${props.name}`.replace(/[^\w-]/g, '-');
+	const n = props.value.length;
+	const over = n > props.max;
+	const input = props.multiline ? (
+		<textarea
+			className="input"
+			id={id}
+			data-path={props.name}
+			rows={3}
+			value={props.value}
+			placeholder={props.placeholder}
+			spellCheck={false}
+			disabled={props.disabled}
+			aria-describedby={over ? `${id}-w` : undefined}
+			onChange={(e) => props.onChange(e.target.value)}
+		/>
+	) : (
+		<input
+			className="input"
+			id={id}
+			data-path={props.name}
+			value={props.value}
+			placeholder={props.placeholder}
+			autoComplete="off"
+			spellCheck={false}
+			disabled={props.disabled}
+			aria-describedby={over ? `${id}-w` : undefined}
+			onChange={(e) => props.onChange(e.target.value.replace(/\n+/g, ' '))}
+		/>
+	);
+	return (
+		<FieldFrame
+			blockKey={props.scope}
+			name={props.name}
+			label={props.label}
+			htmlFor={id}
+			meta={
+				<span className={`field-meta${over ? ' soft-over' : ''}`} data-count={props.max} data-soft="">
+					{n} / {props.max}
+				</span>
+			}
+		>
+			{props.help ? <p className="field-help">{props.help}</p> : null}
+			{input}
+			{over ? (
+				<p className="field-warn" id={`${id}-w`} data-over="">
+					<Icon name="warn" size="sm" />
+					<span>
+						Over {props.max}: {props.overWhy ?? 'it may be cut short'}.
+					</span>
+				</p>
+			) : null}
+		</FieldFrame>
+	);
+}
+
+/** The share image (a page's, or Site Settings' default): image-only, no alt input, a focal point allowed. */
+export function ShareImage(props: { name: string; label: string; help: string; value: unknown }) {
+	const host = useHost();
+	return (
+		<FieldFrame blockKey={host.scope} name={props.name} label={props.label} className="media-field" meta={<span className="field-meta">Images only</span>}>
+			<p className="field-help">{props.help}</p>
+			<MediaSlot path={props.name} field={SHARE_IMAGE} value={props.value} warnings={[]} pickLabel={props.label} noAlt />
+		</FieldFrame>
+	);
+}
+
+/** "Title, description and image set", or "Uses the site’s defaults". */
+export function seoSummary(seo: Record<string, unknown> | undefined): string {
+	const text = (v: unknown) => typeof v === 'string' && v.trim() !== '';
+	const set = [text(seo?.title) && 'title', text(seo?.description) && 'description', parseMedia(seo?.image) && 'image'].filter((x): x is string => !!x);
+	if (!set.length) return 'Uses the site’s defaults';
+	const list = set.length < 2 ? set[0]! : `${set.slice(0, -1).join(', ')} and ${set.at(-1)}`;
+	return `${list[0]!.toUpperCase()}${list.slice(1)} set`;
+}
+
+/** The page's seo host: its fields picked at the document level as `seo.<part>` (so they never ring the form's own `title`). */
+function seoHost(editor: Editor, raw: Record<string, unknown> | undefined, readOnly: boolean): FieldHost {
+	return {
+		scope: SEO_SCOPE,
+		picked: (view: View) => (view.level === 'document' && view.field?.startsWith('seo.') ? view.field.slice(4) : null),
+		pick(path) {
+			if (editor.view.get().field !== `seo.${path}`) editor.view.update({ field: `seo.${path}`, picked: false });
+		},
+		set: (path, value, options) => editor.doc.setField(SEO_SCOPE, path, value, options),
+		removeItem() {},
+		raw: (name) => (raw && Object.hasOwn(raw, name) ? raw[name] : undefined),
+		readOnly,
+	};
+}
+
+/** The group, for the open document. Null for a document without a URL (a collection with no `urlBase`). */
+export function SeoGroup() {
+	const editor = useEditor();
+	const session = useStore(editor.doc.state);
+	const readOnly = useStore(editor.access, (a) => a.readOnly);
+	const brand = useStore(editor.brand, (b) => b.name);
+	const settings = useSiteSettings();
+	const [open, setOpen] = useState(false);
+	const collection = editor.site.collections.find((c) => c.name === session.ref.collection);
+	const raw = useMemo(() => {
+		const base = parseBase(session.base);
+		const seo = base && typeof base === 'object' ? (base as Record<string, unknown>).seo : undefined;
+		return seo && typeof seo === 'object' && !Array.isArray(seo) ? (seo as Record<string, unknown>) : undefined;
+	}, [session.base]);
+	const host = useMemo(() => seoHost(editor, raw, readOnly), [editor, raw, readOnly]);
+	if (!collection?.urlBase || (session.document.kind !== 'sections' && session.document.kind !== 'fields')) return null;
+	const seo = session.document.seo ?? {};
+	const str = (v: unknown) => (typeof v === 'string' ? v : '');
+	const isHome = sameDoc(session.ref, editor.site.home);
+	const defaults = settings?.seo ?? {};
+	const fallback = isHome ? str(defaults.title).trim() || brand : `${session.document.title || session.entry.label} · ${brand}`;
+	return (
+		<details className="fgroup seo" open={open} data-seo="" onToggle={(e) => setOpen((e.currentTarget as HTMLDetailsElement).open)}>
+			<summary>
+				Search and sharing <span className="s">· {seoSummary(session.document.seo)}</span>
+				<Icon name="chev-r" size="sm" />
+			</summary>
+			<div className="in">
+				<FieldHostProvider host={host}>
+					<SoftText
+						scope={SEO_SCOPE}
+						name="title"
+						label="Search title"
+						value={str(seo.title)}
+						max={SEO_TITLE_SOFT_LIMIT}
+						placeholder={fallback}
+						help={`Blank is “${fallback}”.`}
+						overWhy={TITLE_WHY}
+						disabled={readOnly}
+						onChange={(v) => host.set('title', v)}
+					/>
+					<SoftText
+						scope={SEO_SCOPE}
+						name="description"
+						label="Search description"
+						value={str(seo.description)}
+						max={SEO_DESCRIPTION_SOFT_LIMIT}
+						multiline
+						placeholder={str(defaults.description)}
+						help="Blank uses the site default."
+						overWhy={DESC_WHY}
+						disabled={readOnly}
+						onChange={(v) => host.set('description', v.replace(/\n+/g, ' '))}
+					/>
+					<ShareImage
+						name="image"
+						label="Share image"
+						value={seo.image ?? null}
+						help="1200 × 630. Blank uses the site default."
+					/>
+				</FieldHostProvider>
+			</div>
+		</details>
+	);
+}
+
+export { TITLE_WHY, DESC_WHY };
+
+// ── Site Settings as the page's fields need it ───────────────────────────────
+
+/** What a page's fields read from Site Settings: the SEO defaults (fallbacks) and who gets each form's email. */
+export interface SettingsView {
+	seo: Record<string, unknown>;
+	formRecipients: Record<string, string[]>;
+}
+
+const asObject = (v: unknown): Record<string, unknown> => (v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
+const viewOf = (data: Record<string, unknown>): SettingsView => {
+	const recipients: Record<string, string[]> = {};
+	for (const [id, list] of Object.entries(asObject(data.formRecipients))) if (Array.isArray(list)) recipients[id] = list.filter((x): x is string => typeof x === 'string');
+	return { seo: asObject(data.seo), formRecipients: recipients };
+};
+
+interface SettingsSource {
+	store: Store<SettingsView | null>;
+	/** Read Site Settings' draft again, once this tab's own changes to it are sent. The latest read wins. */
+	refresh(): void;
+}
+const settingsSources = new WeakMap<Editor, SettingsSource>();
+
+function settingsFor(editor: Editor): SettingsSource {
+	let source = settingsSources.get(editor);
+	if (source) return source;
+	const store = createStore<SettingsView | null>(null);
+	// While Site Settings is open, its edited values, as they're typed.
+	const follow = (s: ReturnType<Editor['doc']['get']>) => {
+		if (s.document.kind === 'settings') store.set(viewOf(s.document.blocks[0]?.data ?? {}));
+	};
+	follow(editor.doc.get());
+	editor.doc.state.subscribe(follow);
+	let reads = 0;
+	source = {
+		store,
+		refresh() {
+			const ticket = ++reads;
+			// Its own changes first (a recipient added a moment ago), so the draft read has them.
+			void (editor.keeper?.flush() ?? Promise.resolve())
+				.then(() => fetch(`${ENDPOINTS.document}?collection=settings&path=${encodeURIComponent(SETTINGS_PATH)}`, { headers: { Accept: 'application/json' } }))
+				.then(async (response) => {
+					if (!response.ok || ticket !== reads) return;
+					const opened = (await response.json()) as AnyOpenedDocument;
+					if (ticket === reads && opened.document.kind === 'settings' && editor.doc.get().document.kind !== 'settings') store.set(viewOf(opened.document.data as Record<string, unknown>));
+				})
+				.catch(() => undefined);
+		},
+	};
+	settingsSources.set(editor, source);
+	return source;
+}
+
+/**
+ * Site Settings' SEO defaults and form recipients, for fields on another document (the
+ * fallbacks' placeholders, the Form block's "its email goes to"). While Site Settings is
+ * open, its edited values as they're typed; otherwise its draft, read again each time a
+ * field that needs it is shown (someone else, or another tab, may have changed it), with
+ * the last known shown meanwhile. Null until first read.
+ */
+export function useSiteSettings(): SettingsView | null {
+	const editor = useEditor();
+	const source = settingsFor(editor);
+	const view = useStore(source.store);
+	const settingsOpen = useStore(editor.doc.state, (s) => s.document.kind === 'settings');
+	useEffect(() => {
+		if (!settingsOpen) source.refresh();
+	}, [source, settingsOpen]);
+	return view;
+}

package/src/editor/client/fields/SimpleFields.tsx

@@ -0,0 +1,89 @@
+/**
+ * M5a's small fields (Decision 2), each in the field frame and set through the
+ * field host (host.tsx):
+ *
+ *   toggle   `true` / `false`: the mockup's switch, "On" / "Off"
+ *   number   a JSON number, `null` when cleared. Out of range: kept as typed, with
+ *            the reason on the field (Decision 15); the page gets null and shows its default
+ *   date     `"2026-10-15"`, `null` when cleared: the browser's own date input (Decision 2)
+ */
+import { useEffect, useState } from 'react';
+import type { NumberField as NumberDescriptor, ToggleField as ToggleDescriptor } from '../../../fields.ts';
+import { FieldFrame } from './FieldFrame.tsx';
+import { useFieldWarnings, useHost } from './host.tsx';
+import { FieldIcon, Warnings } from './parts.tsx';
+
+interface Props<F> {
+	name: string;
+	label: string;
+	field: F;
+	value: unknown;
+}
+
+const fieldId = (scope: string, name: string) => `f-${scope}-${name}`;
+
+export function ToggleField(props: Props<ToggleDescriptor>) {
+	const host = useHost();
+	const id = fieldId(host.scope, props.name);
+	const on = typeof props.value === 'boolean' ? props.value : props.field.default;
+	const warnings = useFieldWarnings(props.name, props.field, props.value);
+	return (
+		<FieldFrame blockKey={host.scope} name={props.name} label={props.label} help={props.field.help} htmlFor={id}>
+			<button type="button" className="switch" role="switch" id={id} data-path={props.name} aria-checked={on} onClick={() => host.set(props.name, !on)}>
+				<span className="track" />
+				<span>{on ? 'On' : 'Off'}</span>
+			</button>
+			<Warnings warnings={warnings} />
+		</FieldFrame>
+	);
+}
+
+/** What the input shows for a stored number. */
+const shown = (value: unknown) => (typeof value === 'number' && Number.isFinite(value) ? String(value) : '');
+
+export function NumberField(props: Props<NumberDescriptor>) {
+	const host = useHost();
+	const id = fieldId(host.scope, props.name);
+	const { min, max, step } = props.field;
+	// What's typed, kept while it's mid-entry ("-", "1."), so the stored value never rewrites the input under the caret.
+	const [text, setText] = useState(() => shown(props.value));
+	useEffect(() => {
+		const parsed = text.trim() === '' ? null : Number(text);
+		const stored = typeof props.value === 'number' ? props.value : null;
+		if (parsed !== stored) setText(shown(props.value));
+	}, [props.value]);
+	const warnings = useFieldWarnings(props.name, props.field, props.value);
+	const bad = warnings.length > 0;
+	const range = min !== undefined && max !== undefined ? `${min} to ${max}` : min !== undefined ? `${min} or more` : max !== undefined ? `up to ${max}` : '';
+	const onChange = (next: string) => {
+		setText(next);
+		if (next.trim() === '') {
+			host.set(props.name, null);
+			return;
+		}
+		const n = Number(next);
+		if (Number.isFinite(n)) host.set(props.name, n);
+	};
+	return (
+		<FieldFrame blockKey={host.scope} name={props.name} label={props.label} help={props.field.help} htmlFor={id}>
+			<div className="numf">
+				<input
+					className="input"
+					type="number"
+					id={id}
+					data-path={props.name}
+					inputMode="decimal"
+					value={text}
+					min={min}
+					max={max}
+					step={step ?? 'any'}
+					aria-invalid={bad || undefined}
+					aria-describedby={bad ? `${id}-w` : undefined}
+					onChange={(e) => onChange(e.target.value)}
+				/>
+				{range ? <span className="rng">{range}</span> : null}
+			</div>
+			<Warnings warnings={warnings} id={`${id}-w`} />
+		</FieldFrame>
+	);
+}

package/src/editor/client/fields/TextField.tsx

@@ -0,0 +1,51 @@
+/**
+ * Text, one line or several (Decision 12; the line-break rule: a break is `\n`, and
+ * nothing else breaks the text). The same field is typed on the page (page-edit.ts);
+ * what's typed there shows here as it's typed (the store), and what's typed here
+ * re-renders the preview.
+ *
+ * M6: a field with a `max` (the Form block's intro, Decision 17) counts its characters,
+ * and past it the count and a note turn amber. Nothing is refused (it's kept as written).
+ */
+import type { TextField as TextDescriptor } from '../../../fields.ts';
+import { useEditor } from '../context.tsx';
+import { Icon } from '../shell/Icons.tsx';
+import { FieldFrame } from './FieldFrame.tsx';
+import { useFieldHost } from './host.tsx';
+
+export function TextField(props: { blockKey: string; name: string; label: string; field: TextDescriptor; value: unknown }) {
+	const editor = useEditor();
+	// In a field host (host.tsx) the value is set through it; M3's block level passed the block's key.
+	const host = useFieldHost();
+	const id = `f-${props.blockKey}-${props.name}`.replace(/\./g, '-');
+	const value = typeof props.value === 'string' ? props.value : '';
+	const set = (next: string) => {
+		const v = props.field.multiline ? next : next.replace(/\n+/g, ' ');
+		if (host) host.set(props.name, v);
+		else editor.doc.setField(props.blockKey, props.name, v);
+	};
+	const max = props.field.max;
+	const over = max !== undefined && value.length > max;
+	const meta =
+		max !== undefined ? (
+			<span className={`field-meta${over ? ' soft-over' : ''}`} data-count={max} data-soft="">
+				{value.length} / {max}
+			</span>
+		) : undefined;
+	const warn = over ? (
+		<p className="field-warn" id={`${id}-w`} data-over="">
+			<Icon name="warn" size="sm" />
+			<span>Over {max}: it may not fit.</span>
+		</p>
+	) : null;
+	return (
+		<FieldFrame blockKey={props.blockKey} name={props.name} label={props.label} help={props.field.help} htmlFor={id} meta={meta}>
+			{props.field.multiline ? (
+				<textarea className="input" id={id} data-path={props.name} rows={3} value={value} spellCheck={false} aria-describedby={over ? `${id}-w` : undefined} onChange={(e) => set(e.target.value)} />
+			) : (
+				<input className="input" id={id} data-path={props.name} value={value} autoComplete="off" spellCheck={false} aria-describedby={over ? `${id}-w` : undefined} onChange={(e) => set(e.target.value)} />
+			)}
+			{warn}
+		</FieldFrame>
+	);
+}

package/src/editor/client/fields/date.ts

@@ -0,0 +1,73 @@
+/**
+ * The date field's words (pre-M7 polish: the calendar in place of the browser's own
+ * date input). The stored value is still a day, `YYYY-MM-DD`, or null (fields.ts →
+ * parseDay); these turn it into what the box shows ("2 May 2026", the mockup's
+ * fmtDate) and read back what someone types.
+ *
+ * Typed days are read day first (the editor's people write 2/5/2026 for 2 May):
+ * `2026-05-02`, `2/5/2026`, `2.5.2026`, `2-5-2026`, `2 May 2026`, `May 2, 2026`, a
+ * month's first three letters, and a two-digit year as 20xx.
+ */
+import { parseDay } from '../../../fields.ts';
+
+export const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/** "2 May 2026" for `2026-05-02`; '' for anything that isn't a day. */
+export function formatDay(value: unknown): string {
+	const day = parseDay(value);
+	if (!day) return '';
+	const [y, m, d] = day.split('-').map(Number) as [number, number, number];
+	return `${d} ${MONTHS[m - 1]} ${y}`;
+}
+
+const monthOf = (word: string) => {
+	const w = word.toLowerCase();
+	if (w.length < 3) return 0;
+	return MONTHS.findIndex((m) => m.toLowerCase().startsWith(w)) + 1;
+};
+
+const year = (text: string) => (text.length === 2 ? 2000 + Number(text) : Number(text));
+
+const day = (y: number, m: number, d: number) => parseDay(`${String(y).padStart(4, '0')}-${pad(m)}-${pad(d)}`);
+
+/**
+ * What someone typed, read as a day: the day (`YYYY-MM-DD`), null for an empty box
+ * (clears the field), or undefined when it can't be read as a real day.
+ */
+export function readTypedDay(text: string): string | null | undefined {
+	const t = text.trim().replace(/\s+/g, ' ');
+	if (t === '') return null;
+	let m = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(t);
+	if (m) return day(Number(m[1]), Number(m[2]), Number(m[3])) ?? undefined;
+	m = /^(\d{1,2})[/.-](\d{1,2})[/.-](\d{4}|\d{2})$/.exec(t);
+	if (m) return day(year(m[3]!), Number(m[2]), Number(m[1])) ?? undefined;
+	m = /^(\d{1,2})(?:st|nd|rd|th)? ([a-z]+)\.?,? (\d{4}|\d{2})$/i.exec(t);
+	if (m && monthOf(m[2]!)) return day(year(m[3]!), monthOf(m[2]!), Number(m[1])) ?? undefined;
+	m = /^([a-z]+)\.? (\d{1,2})(?:st|nd|rd|th)?,? (\d{4}|\d{2})$/i.exec(t);
+	if (m && monthOf(m[1]!)) return day(year(m[3]!), monthOf(m[1]!), Number(m[2])) ?? undefined;
+	return undefined;
+}
+
+/** A stored day as a local Date at midnight (the calendar's), or undefined. */
+export function dayToDate(value: unknown): Date | undefined {
+	const d = parseDay(value);
+	if (!d) return undefined;
+	const [y, m, dd] = d.split('-').map(Number) as [number, number, number];
+	const at = new Date(y, m - 1, dd);
+	at.setFullYear(y); // years before 100 aren't 19xx
+	return at;
+}
+
+/** A calendar's Date (local) as a stored day. */
+export const dateToDay = (date: Date) => `${String(date.getFullYear()).padStart(4, '0')}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+
+/** Today, as a day, in a time zone (the site's): `en-CA` writes YYYY-MM-DD. */
+export function todayIn(timeZone: string, now = new Date()): string {
+	try {
+		return new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(now);
+	} catch {
+		return dateToDay(now);
+	}
+}

package/src/editor/client/fields/host.tsx

@@ -0,0 +1,172 @@
+/**
+ * Where a field's value lives, so the field components aren't tied to a block
+ * (M5a Phase 4; Phase 5 mounts the same components in a fields document's form).
+ *
+ *   <FieldHostProvider host={host}>
+ *     <FieldControl name="credits" field={descriptor} value={parsed} />
+ *   </FieldHostProvider>
+ *
+ * A host says how to set a value by dotted path (M5a Decision 16: `credits.1.name`),
+ * how to remove a list row with Undo (Decision 14), what the file held for a field
+ * (warnings read the raw value while the field is untouched, Phase 1's note), and
+ * which field is picked. The block level's host is `blockHost(editor, key)`: every
+ * path goes to `editor.doc.setField(key, path, value)`.
+ *
+ * Warnings' context (links to documents that don't exist, references to documents
+ * that don't exist) comes from the editor's document listing: `useWarningContext()`.
+ */
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import { fieldWarnings, getAtPath, parseField, splitPath, type Field, type Fields, type FieldWarning, type WarningContext } from '../../../fields.ts';
+import { mediaFor } from '../media/store.ts';
+import { useEditor, useStore } from '../context.tsx';
+import type { Editor, View } from '../editor.ts';
+import { hiddenDocuments, hiddenPages } from '../../../links.ts';
+
+export interface FieldHost {
+	/**
+	 * What the fields belong to, for element ids and the picked state: the block's
+	 * key in the block level; Phase 5's fields document picks its own (one per form).
+	 */
+	scope: string;
+	/** The path picked among this host's fields (a top-level key or a dotted path), or null. A pure read of the view. */
+	picked(view: View): string | null;
+	/** Pick a field (focus moved into it in the sidebar). `path` may be dotted. */
+	pick(path: string): void;
+	/** Set the value at a dotted path from the host's root: `credits.1.name`, `cta.href`, `featured`. */
+	set(path: string, value: unknown, options?: { undoLabel?: string }): void;
+	/** Remove item `index` of the list at `path`, with Undo under `label` (M2's toast; Decision 14). */
+	removeItem(path: string, index: number, label: string): void;
+	/** The file's value for a top-level field as first read; undefined when the file has none (a new block). */
+	raw(name: string): unknown;
+	/** Read-only (M4: a lock, held edits, signed out). Controls are disabled by the level's fieldset too. */
+	readOnly: boolean;
+}
+
+const HostContext = createContext<FieldHost | null>(null);
+
+export function FieldHostProvider({ host, children }: { host: FieldHost; children: ReactNode }) {
+	return <HostContext.Provider value={host}>{children}</HostContext.Provider>;
+}
+
+/** The host the field is rendered in, or null outside one (M3's fields fall back to their block key). */
+export function useFieldHost(): FieldHost | null {
+	return useContext(HostContext);
+}
+
+/** The host every field needs. Throws outside a FieldHostProvider. */
+export function useHost(): FieldHost {
+	const host = useContext(HostContext);
+	if (!host) throw new Error('A field needs a <FieldHostProvider>');
+	return host;
+}
+
+/** Is `path` the field `name` itself or a path inside it? */
+export const within = (path: string | null | undefined, name: string): boolean => !!path && (path === name || path.startsWith(`${name}.`));
+
+const rawCache = new Map<string, unknown>();
+
+/** The file's text as a value (cached per text, so a re-render doesn't re-parse); undefined when it isn't JSON. */
+export function parseBase(base: string): unknown {
+	if (rawCache.has(base)) return rawCache.get(base);
+	let value: unknown;
+	try {
+		value = JSON.parse(base);
+	} catch {
+		value = undefined;
+	}
+	if (rawCache.size > 8) rawCache.clear();
+	rawCache.set(base, value);
+	return value;
+}
+
+/** A block's raw fields in the file as first read (by its `source`), or undefined for an added block. */
+export function rawBlock(base: string, source: number | null): Record<string, unknown> | undefined {
+	if (source === null) return undefined;
+	const doc = parseBase(base);
+	const blocks = doc && typeof doc === 'object' ? (doc as { blocks?: unknown }).blocks : undefined;
+	const raw = Array.isArray(blocks) ? blocks[source] : undefined;
+	return raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : undefined;
+}
+
+/** The block level's host: one block of the open document, by its key. */
+export function blockHost(editor: Editor, key: string, raw: Record<string, unknown> | undefined, readOnly: boolean): FieldHost {
+	return {
+		scope: key,
+		picked: (view) => (view.level === 'block' && view.block === key ? view.field : null),
+		pick(path) {
+			const view = editor.view.get();
+			if (view.field !== path) editor.view.update({ field: path, picked: false });
+		},
+		set: (path, value, options) => editor.doc.setField(key, path, value, options),
+		removeItem(path, index, label) {
+			editor.doc.removeItem(key, path, index, { label });
+			editor.announce(`${label}. Undo with Command Z.`);
+		},
+		raw: (name) => (raw && Object.hasOwn(raw, name) ? raw[name] : undefined),
+		readOnly,
+	};
+}
+
+/**
+ * What warnings check against, from the editor's document listing: every document's
+ * address and the site's code routes (internal links, Decision 4) and whether a document exists (references,
+ * Decision 6).
+ */
+export function useWarningContext(): WarningContext {
+	const editor = useEditor();
+	const documents = useStore(editor.documents);
+	// M6c G4 (Decision 10): the library's file keys, once read (media/store.ts reads them the first time an opened document holds a /files/ link).
+	const files = useStore(mediaFor(editor).files, (l) => l.list);
+	return useMemo(() => {
+		const ids = new Set(documents.map((d) => `${d.collection}/${d.path}`));
+		const keys = files ? new Set(files.map((f) => f.key)) : null;
+		return {
+			addresses: documents.map((d) => d.url),
+			// M9 Decision 7: a link to a hidden page warns.
+			hiddenPages: hiddenPages(documents),
+			// ...and so does a reference to one.
+			hiddenDocuments: hiddenDocuments(documents),
+			// M8 trial (item 3): an address the site's own code serves exists too.
+			codeRoutes: editor.site.codeRoutes ?? [],
+			documentExists: (collection: string, path: string) => ids.has(`${collection}/${path}`),
+			...(keys ? { fileExists: (key: string) => keys.has(key) } : {}),
+		};
+	}, [documents, files]);
+}
+
+const same = (a: unknown, b: unknown) => a === b || JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * A field's warnings (Phase 1's fieldWarnings): from the file's raw value while the
+ * field is untouched (so a heading where headings are off, kept in the file, is
+ * still said), from the edited value once it's changed.
+ */
+export function useFieldWarnings(name: string, field: Field, value: unknown): FieldWarning[] {
+	const host = useHost();
+	const context = useWarningContext();
+	// A field inside a group or a list item (`left.heading`): the file's value at that path in its top-level field.
+	const [top, ...inside] = splitPath(name);
+	const raw = inside.length ? getAtPath(host.raw(top!), inside.join('.')) : host.raw(name);
+	return useMemo(() => {
+		const untouched = raw !== undefined && same(parseField(field, raw), value);
+		return fieldWarnings(field, untouched ? raw : value, context);
+	}, [field, raw, value, context]);
+}
+
+/**
+ * Every warning in a set of fields (a form's, or a section builder's page fields), by
+ * the same rule as each field's own (useFieldWarnings): the file's value while a field is
+ * untouched, the edited one once it's changed. For a section's mark (GroupField.tsx →
+ * FieldSection), so a closed section says it holds a warning.
+ */
+export function fieldsWarnings(fields: Fields, data: Record<string, unknown>, raw: Record<string, unknown> | undefined, context: WarningContext): FieldWarning[] {
+	return Object.entries(fields).flatMap(([name, field]) => {
+		const was = raw && Object.hasOwn(raw, name) ? raw[name] : undefined;
+		const untouched = was !== undefined && same(parseField(field, was), data[name]);
+		return fieldWarnings(field, untouched ? was : data[name], context, name);
+	});
+}
+
+/** Warnings at a path relative to the field: `''` the field's own, `'1'` and `'1.href'` the second item's. */
+export const warningsAt = (warnings: readonly FieldWarning[], path: string): FieldWarning[] =>
+	warnings.filter((w) => w.path === path || w.path.startsWith(`${path}.`));