@riducms/plugin 0.1.4 → 0.2.0

package/src/authoring.ts

@@ -1,6 +1,7 @@
-import type { SchemaCollection, SchemaField } from "@riducms/protocol";
-import type { Component } from "svelte";
+import type { SchemaCollection, SchemaField, ValidationIssue } from "@riducms/protocol";
+import type { Component, Snippet } from "svelte";
 
+/** A saved document returned by Ridu. Check custom fields before using their unknown values. */
 export type FieldDocument = Record<string, unknown> & {
 	id: string;
 	createdAt?: string;
@@ -13,6 +14,7 @@ export type FieldDocument = Record<string, unknown> & {
 	};
 };
 
+/** A condition that narrows documents offered by the reference browser. It does not grant access. */
 export interface FieldReferenceFilter {
 	field: string;
 	operator:
@@ -27,28 +29,184 @@ export interface FieldReferenceFilter {
 	value: string | number | boolean;
 }
 
+/**
+ * Props for Ridu's related-document picker and editor. Render the component supplied
+ * as `authoring.referenceBrowser`; your `onCommit` decides how selected IDs change
+ * your field. Saving a related document inside the browser is a separate server save.
+ */
 export interface FieldReferenceBrowserProps {
+	/** Whether the browser is visible. */
 	open?: boolean;
+	/** The relationship/upload field whose rules the browser should use. */
 	field: SchemaField;
+	/** The target collection's resolved schema, available from `authoring.collections`. */
 	collection: SchemaCollection;
+	/** Allow multiple selections when true; otherwise select at most one document. */
 	hasMany: boolean;
+	/** IDs currently selected by your editor. */
 	selectedIDs: readonly string[];
+	/** Further restrict editing; false cannot override Ridu's access restrictions. */
 	readOnly?: boolean;
+	/** Open this already-loaded document for editing instead of starting at the list. */
 	initialDocument?: FieldDocument;
+	/** Fetch and open this document when `initialDocument` is not supplied. */
 	initialDocumentID?: string;
+	/** Limit selectable documents; the server still applies its own access rules. */
 	optionFilter?: FieldReferenceFilter | readonly FieldReferenceFilter[];
+	/** Initial values for a new related document, not changes to an existing document. */
 	defaultValues?: Readonly<Record<string, unknown>>;
+	/** Allow creation when access permits it. Set false to hide creation. */
 	allowCreate?: boolean;
+	/** Content locale for loading and editing related documents. */
 	locale?: string;
+	/**
+	 * Called when the user confirms the selection. Update your field here.
+	 * Return false (or resolve to false) to keep the browser open. Returning void or
+	 * true accepts the selection and closes it while editing remains allowed. A thrown
+	 * error/rejected promise keeps it open and Ridu displays an error notification.
+	 */
 	onCommit: (ids: string[]) => void | boolean | Promise<void | boolean>;
+	/** Called when the browser closes; update your open/closed UI state here. */
 	onClose: () => void;
 }
 
+/**
+ * Select an existing group of ordinary fields inside a plugin value, such as the
+ * fields of one rich-text card. Go must declare the embedded tree and its schemas.
+ * Ridu locates the data by its stable identity, even when the card moves.
+ */
+export interface EmbeddedSchemaFormScope {
+	/** The embedded tree key declared by the Go field, for example `"widgets"`. */
+	treeKey: string;
+	/** The existing item's stable ID, as declared by that tree's identity configuration. */
+	identity: string;
+	/** Display without editing; false does not override document or field access rules. */
+	readOnly?: boolean;
+}
+
+/** Select a Go-declared embedded variant when creating or copying an item's field data. */
+export interface EmbeddedSchemaVariantScope {
+	/** The embedded tree key declared by the Go field. */
+	treeKey: string;
+	/** The tree case's configured tag value, not the name of the property holding the tag. */
+	caseTag: string;
+	/** The variant key within that case, for example `"hero"`. */
+	variantSlug: string;
+}
+
+/**
+ * A temporary Apply/Cancel form for fields inside one plugin item.
+ * Its edits stay separate from the document until your Apply handler accepts them.
+ * This is not a saved document draft/version and cannot save to the server itself.
+ * Ridu tracks pending edits so the outer form can ask the user to Apply or Cancel.
+ */
+export interface EmbeddedSchemaDraft {
+	/** Unique ID for this temporary editing session. */
+	readonly id: string;
+	/** Stable ID of the item being edited, or the proposed ID for a new item. */
+	readonly identity: string;
+	/** Whether edits await Apply/Cancel. A proposed new item counts as dirty even before typing. */
+	readonly dirty: boolean;
+	/**
+	 * Whether the draft is no longer usable. Removal, changed source data, document/
+	 * locale/schema/access changes, discard, or closing the parent editor can expire it.
+	 * Reopen a draft instead of applying old data. Moving the same item alone is allowed.
+	 */
+	readonly stale: boolean;
+	/** Current validation issues shown in this draft. */
+	readonly issues: readonly ValidationIssue[];
+	/** Copy the draft's current field values; throws if it has expired or editing is blocked. */
+	payload(): Record<string, unknown>;
+	/**
+	 * Check the draft against its declared field rules and update `issues`.
+	 * Returns whether it passes. Go validators and hooks run later, on document save.
+	 * The guarded plugin method throws if the draft has expired or editing is blocked.
+	 */
+	validate(): boolean;
+	/** Release this draft and abandon its pending edits. Safe to call more than once. */
+	discard(): void;
+}
+
+/** Options for rendering a draft in Ridu's drawer with Apply and Cancel controls. */
+export interface EmbeddedSchemaDraftEditorProps {
+	/** A draft created by this field's `authoring.beginSchemaDraft`. */
+	draft: EmbeddedSchemaDraft;
+	/** Optional heading for the drawer. */
+	title?: string;
+	/**
+	 * Receives checked field data when Apply succeeds. Insert or update the item in
+	 * your plugin value and call `field.set` (or serialize your editor's updated state).
+	 * Close your drawer UI here. Ridu discards the temporary draft after this handler
+	 * returns; it does not insert data into your plugin value or save the document.
+	 */
+	onApply: (payload: Record<string, unknown>) => void;
+	/** Close your editor UI after the pending draft has been discarded. */
+	onCancel: () => void;
+}
+
+/**
+ * Ridu tools supplied to a plugin field for embedded forms and related documents.
+ * Optional methods must be checked before use. They work within the current field's
+ * lifetime: async reads/requests reject if the field expires before they complete.
+ * Already-dispatched server work is not undone. Cancel requests when appropriate,
+ * and prevent an older request from overwriting a newer result in your own UI.
+ */
 export interface FieldAuthoringHost {
+	/**
+	 * Render the ordinary fields of an existing embedded item using
+	 * `{@render authoring.schemaForm({ treeKey, identity })}`.
+	 * Edits update the parent document's unsaved form immediately. Use a draft below
+	 * if the user needs Apply/Cancel. Neither approach saves the document itself.
+	 */
+	schemaForm?: Snippet<[EmbeddedSchemaFormScope]>;
+	/**
+	 * Start a temporary Apply/Cancel form. Pass `{ treeKey, identity }` to edit an
+	 * existing item, or `{ treeKey, caseTag, variantSlug }` to prepare a new one using
+	 * Go-declared field defaults. Creation does not insert anything into your value.
+	 * Call `discard` when abandoning a draft; closing the field also cleans it up.
+	 */
+	beginSchemaDraft?: (
+		scope: EmbeddedSchemaFormScope | EmbeddedSchemaVariantScope
+	) => EmbeddedSchemaDraft;
+	/** Render a draft in Ridu's drawer; your `onApply` writes the accepted data into your plugin value. */
+	schemaDraftEditor?: Snippet<[EmbeddedSchemaDraftEditorProps]>;
+	/** Read current parent-form issues for an existing embedded item, for example for a card badge. */
+	schemaIssues?: (scope: EmbeddedSchemaFormScope) => readonly ValidationIssue[];
+	/**
+	 * Copy an item's ordinary field data and give its schema-declared nested rows/items
+	 * fresh IDs. Use when duplicating to avoid sharing identities. This does not insert
+	 * the copy or copy your outer plugin item; update that structure in your editor.
+	 */
+	copySchemaPayload?: (
+		scope: EmbeddedSchemaVariantScope,
+		payload: Readonly<Record<string, unknown>>
+	) => Record<string, unknown>;
+	/** Collection definitions available in the current admin schema, not fetched documents. */
 	readonly collections: readonly SchemaCollection[];
+	/**
+	 * Admin change counter: it advances when Ridu is notified that documents changed.
+	 * Useful for refreshing lookup UI; it is not a document's saved `_revision` number.
+	 */
 	readonly documentRevision: number;
+	/** The content locale being edited, separate from the admin interface language. */
 	readonly locale?: string;
+	/** Related-document picker/editor component. Its `onCommit` handler updates your field. */
 	referenceBrowser: Component<FieldReferenceBrowserProps>;
+	/**
+	 * Fetch a saved document by collection slug and ID in the current content locale.
+	 * Does not include unsaved edits from the current form. Rejects on request failure
+	 * or if this field expires while waiting. Returns a copy; edits to it are local.
+	 */
 	findDocument(collection: string, id: string, signal?: AbortSignal): Promise<FieldDocument>;
+	/**
+	 * POST to an endpoint declared by this renderer's paired Go plugin. Supply the
+	 * plugin-relative path, not an arbitrary URL. This sends a real server request;
+	 * it does not automatically update or save the containing form.
+	 *
+	 * Requires an editable field and rejects if the field expires while waiting.
+	 * Server work already sent may still finish. The `Result` generic describes your
+	 * expected response; it does not validate it. Use `unknown` and decode the result
+	 * when the response shape needs checking.
+	 */
 	requestPlugin?<Result>(path: string, body: unknown, signal?: AbortSignal): Promise<Result>;
 }

package/src/component-config.ts

@@ -0,0 +1,51 @@
+/** Validates the explicit settings selected for a static component before decoding. */
+export function decodeComponentConfig(
+	selection: { config?: unknown } | undefined,
+	decoder: ((value: unknown) => unknown) | undefined
+): unknown {
+	const supplied = selection !== undefined && Object.hasOwn(selection, "config");
+	if (!supplied) {
+		if (decoder !== undefined)
+			throw new Error("config is required by decodeConfig; supply a configuration object in Go");
+		return undefined;
+	}
+	if (decoder === undefined)
+		throw new Error(
+			"config was supplied but there is no decodeConfig; remove the Go configuration or register a decoder"
+		);
+	if (typeof decoder !== "function") throw new Error("decodeConfig must be a synchronous function");
+	const raw = selection.config;
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+		throw new Error("supplied config must be a finite JSON object");
+	const seen = new Set<object>();
+	const copy = (value: unknown, depth: number): unknown => {
+		if (depth > 100) throw new Error("config exceeds the supported JSON depth");
+		if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+		if (
+			typeof value !== "object" ||
+			(!Array.isArray(value) &&
+				Object.getPrototypeOf(value) !== Object.prototype &&
+				Object.getPrototypeOf(value) !== null) ||
+			seen.has(value)
+		)
+			throw new Error("config must contain finite, acyclic JSON data");
+		seen.add(value);
+		const result = Array.isArray(value)
+			? Array.from(value, (child) => copy(child, depth + 1))
+			: Object.fromEntries(
+					Object.entries(value).map(([key, child]) => [key, copy(child, depth + 1)])
+				);
+		seen.delete(value);
+		return result;
+	};
+	const decoded = decoder(copy(raw, 0));
+	if (
+		decoded !== null &&
+		(typeof decoded === "object" || typeof decoded === "function") &&
+		"then" in decoded &&
+		typeof decoded.then === "function"
+	)
+		throw new Error("config decoders must be synchronous");
+	return decoded;
+}

package/src/editor/field.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import { FieldFrame } from "@riducms/ui";
+	import type { FieldBinding } from "./types";
+
+	let { field, children }: { field: Pick<FieldBinding, "schema" | "issues">; children: Snippet } =
+		$props();
+</script>
+
+<div data-field-path={field.schema.path}>
+	<FieldFrame
+		controlID={field.schema.id}
+		label={field.schema.admin.label}
+		required={field.schema.required}
+		readOnly={field.schema.admin.readOnly}
+		description={field.schema.admin.description}
+		errors={field.issues.map((issue) => issue.message)}
+	>
+		{@render children()}
+	</FieldFrame>
+</div>

package/src/editor/field.ts

@@ -0,0 +1,9 @@
+/**
+ * Adds a label, description and validation messages around your custom field input.
+ *
+ * Import `Field from "@riducms/plugin/editor/field"` and wrap your input in
+ * `<Field {field}>...</Field>` to show its label, description and validation errors.
+ * Your input still needs its value, read-only state and change handler. The wrapper
+ * does not register the field or own form values; Ridu already does that.
+ */
+export { default } from "./field.svelte";

package/src/editor/index.ts

@@ -0,0 +1,3 @@
+export type { FieldBinding, FieldEditorProps, FieldEditorType, FieldEditorValue } from "./types";
+export { defineFieldEditor } from "./registry";
+export type { FieldEditorDefinition, RegisteredFieldEditor } from "./registry";

package/src/editor/registry.ts

@@ -0,0 +1,174 @@
+import { bindSchemaManifest } from "@riducms/protocol";
+import { resolveBlockTypes } from "@riducms/protocol";
+import type { Component } from "svelte";
+import type { SchemaField, SchemaManifest } from "@riducms/protocol";
+
+import type { FieldEditorProps, FieldEditorType } from "./types";
+import { decodeComponentConfig } from "../component-config";
+
+export const localEditorReference = /^app:[A-Za-z][A-Za-z0-9_]*$/;
+const editorTypes = new Set<string>([
+	"text",
+	"textarea",
+	"email",
+	"date",
+	"code",
+	"number",
+	"checkbox",
+	"text-list",
+	"number-list",
+]);
+
+/**
+ * A custom field input and its optional settings decoder. `type` must match
+ * the Go field's type. When Config is not undefined, `decodeConfig` is required;
+ * naming a config type alone does not check serialized settings.
+ */
+export type FieldEditorDefinition<Type extends FieldEditorType, Config = undefined> = {
+	/** The existing field type to display differently, for example `"text"` or `"number"`. */
+	type: Type;
+	/** Svelte component accepting the matching `FieldEditorProps<Type, Config>`. */
+	component: Component<FieldEditorProps<NoInfer<Type>, NoInfer<Config>>>;
+} & (0 extends 1 & Config
+	? { decodeConfig: (value: unknown) => Config }
+	: [Config] extends [never]
+		? { decodeConfig: (value: unknown) => Config }
+		: [Config] extends [undefined]
+			? { decodeConfig?: (value: unknown) => Config }
+			: { decodeConfig: (value: unknown) => Config });
+
+const registration = Symbol("ridu-field-editor");
+const registeredEditors = new WeakSet<RegisteredFieldEditor>();
+/** Registration returned by `defineFieldEditor`; store it in `defineAdmin({ fields: ... })`. */
+export interface RegisteredFieldEditor {
+	readonly [registration]: true;
+	readonly type: FieldEditorType;
+	// Erasure must not advertise that a specific component accepts every value/config.
+	// Only the validated host render boundary may recover its props.
+	readonly component: Component<never>;
+	decode(field: SchemaField): unknown;
+}
+
+/**
+ * Register a Svelte component to replace a field input in your application.
+ * Supports text, textarea, email, date, code, number, checkbox, text-list and number-list fields.
+ *
+ * Put the result under an `app:name` key in `defineAdmin({ fields: ... })` and
+ * select that same key in Go with `field.Admin{Editor: field.Component("app:name")}`. The Go field keeps
+ * its original storage, validation and filtering behaviour.
+ *
+ * `type` and `component` are required. The component receives `FieldEditorProps`
+ * for that type: read `field.value`, update the unsaved form with `field.set`, and
+ * render labels/errors with the `Field` component from `@riducms/plugin/editor/field`.
+ * Ridu provides the value type, so this helper needs no `decodeValue` option.
+ *
+ * Add `decodeConfig` only when Go supplies settings through `field.Component`.
+ * It checks unknown JSON and returns the component's `config` prop synchronously;
+ * throw a useful error for invalid settings. With a decoder, Go must supply an
+ * object even for empty settings. Without one, omit the settings argument in Go.
+ * TypeScript infers the `Config` type from the decoder's return value.
+ *
+ * @param definition The existing field type, Svelte component, and optional settings decoder.
+ * @returns A frozen registration for `defineAdmin`'s `fields` map. This does not
+ * render the component, select it on a Go field, or change the stored value type.
+ * @throws If the type is unsupported or the component is invalid. `ridu check`
+ * also checks the selected Go field type and its settings before deployment.
+ * @example
+ * ```ts
+ * import { defineAdmin } from '@riducms/plugin/admin';
+ * import { defineFieldEditor } from '@riducms/plugin/editor';
+ * import { generatedAdminPlugins } from './ridu.plugins.generated';
+ * import TitleField from './components/title-field.svelte';
+ *
+ * export default defineAdmin({
+ *   plugins: generatedAdminPlugins,
+ *   fields: {
+ *     'app:titleCounter': defineFieldEditor({ type: 'text', component: TitleField })
+ *   }
+ * });
+ * ```
+ */
+export function defineFieldEditor<const Type extends FieldEditorType, Config = undefined>(
+	definition: FieldEditorDefinition<Type, Config>
+): RegisteredFieldEditor {
+	if (!editorTypes.has(definition.type) || typeof definition.component !== "function")
+		throw new Error("A field editor requires a supported field type and a Svelte component.");
+	const { type, component, decodeConfig } = definition;
+	const editor = Object.freeze({
+		[registration]: true as const,
+		type,
+		component,
+		decode(field: SchemaField): unknown {
+			const reference = field.admin.editor?.reference;
+			if (field.type !== type)
+				throw new Error(
+					`Editor ${reference} expects ${type}, but ${field.path} is ${field.type}. Change the Go editor selection or registration type.`
+				);
+			try {
+				return decodeComponentConfig(field.admin.editor, decodeConfig);
+			} catch (error) {
+				throw new Error(
+					`Editor ${reference} config for ${field.path} is invalid: ${error instanceof Error ? error.message : String(error)}. Fix the field component config in Go or the decoder in admin/src/admin.config.ts.`
+				);
+			}
+		},
+	});
+	registeredEditors.add(editor);
+	return editor;
+}
+
+export interface FieldEditorConfig {
+	/** Custom field inputs selected by Go `field.Admin{Editor: field.Component("app:name")}`. Use `defineFieldEditor` for each entry. */
+	fields?: Readonly<Record<`app:${string}`, RegisteredFieldEditor>>;
+}
+
+/** The application owns one static configuration; packaged plugins retain their pairing contracts. */
+export function validateFieldEditorRegistrations(config: FieldEditorConfig): void {
+	for (const [reference, editor] of Object.entries(config.fields ?? {})) {
+		if (!localEditorReference.test(reference))
+			throw new Error(
+				`Invalid editor reference ${reference}; expected app:name in admin/src/admin.config.ts.`
+			);
+		if (!registeredEditors.has(editor))
+			throw new Error(`Editor ${reference} must use defineFieldEditor.`);
+	}
+}
+
+/** Uses the same executable registrations and decoders in the browser and build checks. */
+export function validateAdminEditors(
+	config: FieldEditorConfig,
+	manifest: Pick<SchemaManifest, "collections" | "globals" | "blocks">
+): void {
+	validateFieldEditorRegistrations(config);
+	const failures: string[] = [];
+	bindSchemaManifest(manifest);
+	const inspect = (fields: readonly SchemaField[], owner: string) => {
+		for (const field of fields) {
+			const reference = field.admin.editor?.reference;
+			if (reference !== undefined) {
+				const editor = config.fields?.[reference as `app:${string}`];
+				try {
+					if (!localEditorReference.test(reference))
+						throw new Error(`Malformed editor reference ${reference}; expected app:name.`);
+					if (editor === undefined)
+						throw new Error(
+							`Editor ${reference} is not registered. Register it in admin/src/admin.config.ts or change the field component in Go.`
+						);
+					editor.decode(field);
+				} catch (error) {
+					failures.push(
+						`${owner}.${field.path}: ${error instanceof Error ? error.message : String(error)}`
+					);
+				}
+			}
+			for (const tree of field.plugin?.embeddedTrees ?? [])
+				for (const item of tree.cases)
+					for (const variant of resolveBlockTypes(item)) inspect(variant.fields, owner);
+			if (field.nested !== undefined) inspect(field.nested.fields, owner);
+			for (const block of resolveBlockTypes(field.blocks) ?? []) inspect(block.fields, owner);
+		}
+	};
+	for (const collection of manifest.collections) inspect(collection.fields, collection.slug);
+	for (const global of manifest.globals ?? []) inspect(global.fields, global.slug);
+	if (failures.length !== 0) throw new Error(failures.join("\n"));
+}

package/src/editor/types.ts

@@ -0,0 +1,104 @@
+import type { SchemaField, ValidationIssue } from "@riducms/protocol";
+import type { FieldAuthoringHost } from "../authoring";
+import type { FieldDocumentForm, FieldLiveValidation } from "../form";
+import type { AdminI18n } from "../i18n";
+
+/** Field types whose inputs you can replace with a custom component. Lists contain primitive strings or numbers; the list is one field. */
+export type FieldEditorType =
+	| "text"
+	| "textarea"
+	| "email"
+	| "date"
+	| "code"
+	| "number"
+	| "checkbox"
+	| "text-list"
+	| "number-list";
+/** The value your field component reads and writes. Date and code fields contain strings. */
+export type FieldEditorValue<Type extends FieldEditorType> = Type extends "text-list"
+	? string[]
+	: Type extends "number-list"
+		? number[]
+		: Type extends "number"
+			? number
+			: Type extends "checkbox"
+				? boolean
+				: string;
+
+/**
+ * The current field value, validation messages and input controls for your component.
+ * Ridu registers it and cleans it up. In arrays/blocks it follows the row's stable
+ * `_key` through reorder. Removing the row, closing the editor, or replacing the
+ * document, locale, schema or saved/reset values makes it stale. Old connections
+ * cannot edit a new row that happens to occupy the same position.
+ */
+export interface FieldBinding<Type extends FieldEditorType = FieldEditorType> {
+	/**
+	 * A copy of the resolved field definition, including its current path, label and rules.
+	 * `schema.admin.readOnly` reflects field configuration and access, not a pending document save.
+	 */
+	readonly schema: SchemaField & { type: Type };
+	/** Current form value, including unsaved edits; null/undefined mean empty or absent. */
+	readonly value: FieldEditorValue<Type> | null | undefined;
+	/** Current validation issues, including errors returned by a document save. */
+	readonly issues: readonly ValidationIssue[];
+	/** Opted-in server feedback, managed by the host; save validation stays independent. */
+	readonly liveValidation: FieldLiveValidation;
+	/** Whether changes are blocked right now, including during a document save. `set` checks this again when called. */
+	readonly readOnly: boolean;
+	/** True once the connection expires. Value becomes undefined, issues empty and writes throw. */
+	readonly stale: boolean;
+	/**
+	 * ID, name and accessibility attributes for your input. Spread these onto the
+	 * control, and handle `field.readOnly` and value changes separately.
+	 * The optional Field wrapper supplies the matching label and error messages.
+	 * Native `required` is false for boolean and list controls: a list requires
+	 * entries, not nonempty text in every item. Ridu validates the container on save.
+	 */
+	readonly inputProps: {
+		id: string;
+		name: string;
+		required: boolean;
+		"aria-invalid": boolean;
+		"aria-describedby": string | undefined;
+		"aria-errormessage": string | undefined;
+	};
+	/**
+	 * Change the value in the unsaved form; `null` clears it. This does not save to
+	 * the server. Throws if stale, read-only, or given the wrong value type. Lists are copied on reads and writes.
+	 * Normal field validation and server authorization still apply on document save.
+	 */
+	set(value: FieldEditorValue<Type> | null): void;
+}
+
+/**
+ * Props for a custom field input selected by Go `field.Admin{Editor: field.Component("app:name")}` and
+ * registered with `defineFieldEditor` in `admin/src/admin.config.ts`.
+ * Use `FieldEditorProps<"text", MyConfig>` for a text editor with decoded settings.
+ */
+export type FieldEditorProps<Type extends FieldEditorType = FieldEditorType, Config = undefined> = {
+	/** Read the current value and update it with `field.set(...)`. */
+	field: FieldBinding<Type>;
+	/** Interface translations and formatting using the admin's language/preferences. */
+	i18n: AdminI18n;
+	/**
+	 * Read other values in this unsaved document form. These methods return copies
+	 * and expire with the editor. Local editors update only their own `field`;
+	 * this form interface does not expose `bind` for writing another field.
+	 */
+	form: Pick<FieldDocumentForm, "contentLocale" | "resource" | "get" | "issuesFor"> &
+		Partial<Pick<FieldDocumentForm, "snapshot">>;
+	/**
+	 * Browse or fetch related documents. These are the local editor's available tools;
+	 * a local editor mounted in an embedded form reads and writes that form’s detached payload.
+	 * The containing paired plugin owns Apply/Cancel and Go plugin requests.
+	 */
+	authoring: Pick<
+		FieldAuthoringHost,
+		"collections" | "documentRevision" | "referenceBrowser" | "findDocument"
+	> & { readonly locale: string | undefined };
+} & ([Config] extends [undefined]
+	? { config?: never }
+	: {
+			/** Go settings validated by the registration's decoder before rendering. */ config: Config;
+		});