@riducms/admin 0.1.4 → 0.2.0

package/src/core/forms/embedded-schema-draft.svelte.ts

@@ -0,0 +1,335 @@
+import { resolveBlockTypes } from "@riducms/protocol";
+import type {
+	AdminI18n,
+	EmbeddedSchemaDraft,
+	EmbeddedSchemaFormScope,
+	EmbeddedSchemaVariantScope,
+} from "@riducms/plugin";
+import type { SchemaField } from "@riducms/protocol";
+import { FormController } from "@admin/core/forms/form-controller.svelte";
+import { embeddedOccurrences } from "@admin/core/forms/embedded-fields";
+import { cloneFormValue, initialFormValues } from "@admin/core/forms/form-schema";
+import { validateFormValues } from "@admin/core/forms/form-validation";
+import { cloneFieldForPaste } from "@admin/fields/field-clipboard";
+import { fieldAccessPath, scopeRepeatedRowField } from "@admin/fields/nested/scoped-field";
+import { indexFieldValues, canonicalIssueTarget } from "@admin/core/forms/form-issue-correlation";
+
+/** Rendering state stays private; the plugin receives only the public detached edit. */
+export interface HostedSchemaDraft {
+	draft: EmbeddedSchemaDraft;
+	form: FormController;
+	fields: SchemaField[];
+}
+
+export function embeddedVariant(field: SchemaField, scope: EmbeddedSchemaVariantScope) {
+	const tree = field.plugin?.embeddedTrees?.find((candidate) => candidate.key === scope.treeKey);
+	const branch = tree?.cases.find((candidate) => candidate.tagValue === scope.caseTag);
+	const block = resolveBlockTypes(branch).find((candidate) => candidate.slug === scope.variantSlug);
+	if (tree === undefined || branch === undefined || block === undefined)
+		throw new Error(
+			"The embedded schema is no longer available. Reload its configuration before editing."
+		);
+	return { tree, branch, block };
+}
+
+export function copyEmbeddedSchemaPayload(
+	field: SchemaField,
+	scope: EmbeddedSchemaVariantScope,
+	payload: Readonly<Record<string, unknown>>
+) {
+	const { branch, block } = embeddedVariant(field, scope);
+	if (payload[branch.discriminator] !== block.slug)
+		throw new Error("The copied payload does not match the configured embedded schema.");
+	const copy = cloneFormValue(payload) as Record<string, unknown>;
+	for (const child of block.fields) {
+		if (Object.hasOwn(copy, child.name))
+			copy[child.name] = cloneFieldForPaste(child, copy[child.name]);
+	}
+	copy[branch.identity] = crypto.randomUUID();
+	return copy;
+}
+
+export function createEmbeddedSchemaDraft(
+	parent: FormController,
+	getField: () => SchemaField,
+	scope: EmbeddedSchemaFormScope | EmbeddedSchemaVariantScope,
+	i18n: AdminI18n,
+	isActive: () => boolean = () => true
+): HostedSchemaDraft {
+	const field = getField();
+	// Rendered fields carry DOM-specific IDs. Detached validation keeps manifest field identity.
+	const authoredField =
+		indexFieldValues(parent.schemaFields, parent.values).find(
+			(location) => location.path === field.path
+		)?.schema ?? field;
+	if (
+		("readOnly" in scope && scope.readOnly) ||
+		parent.submitting ||
+		field.admin.readOnly ||
+		!parent.canWrite(field.path, fieldAccessPath(field))
+	)
+		throw new Error("This field is read-only.");
+	const revision = parent.revision;
+	const locale = parent.contentLocale;
+	const signature = JSON.stringify(field.plugin?.embeddedTrees);
+	const existing = "identity" in scope;
+	const findOccurrence = () =>
+		embeddedOccurrences(getField(), parent.get(getField().path)).occurrences.find(
+			(occurrence) =>
+				occurrence.tree.key === scope.treeKey && existing && occurrence.identity === scope.identity
+		);
+	const occurrence = existing ? findOccurrence() : undefined;
+	if (existing && occurrence === undefined)
+		throw new Error("The embedded occurrence no longer exists.");
+	const variant =
+		occurrence === undefined
+			? embeddedVariant(authoredField, scope as EmbeddedSchemaVariantScope)
+			: embeddedVariant(authoredField, {
+					treeKey: occurrence.tree.key,
+					caseTag: occurrence.case.tagValue,
+					variantSlug: occurrence.block.slug,
+				});
+	const { branch, block } = variant;
+	const accessState = () => {
+		const currentPath = existing ? findOccurrence()?.path : undefined;
+		const canonical = block.fields.map(fieldAccessPath);
+		const entries = Object.entries(parent.access?.fields ?? {})
+			.filter(
+				([path]) =>
+					path === getField().path ||
+					path === fieldAccessPath(getField()) ||
+					(currentPath !== undefined &&
+						(path === currentPath || path.startsWith(`${currentPath}.`))) ||
+					canonical.some((prefix) => path === prefix || path.startsWith(`${prefix}.`))
+			)
+			.map(([path, capability]) => [
+				currentPath !== undefined && path.startsWith(currentPath)
+					? "$payload" + path.slice(currentPath.length)
+					: path,
+				capability,
+			])
+			.sort((left, right) => String(left[0]).localeCompare(String(right[0])));
+		return JSON.stringify({
+			operations: parent.access?.operations,
+			mode: parent.accessMode,
+			entries,
+		});
+	};
+	const initialAccess = accessState();
+	const id = `draft_${crypto.randomUUID().replaceAll("-", "")}`;
+	const identity = occurrence?.identity ?? crypto.randomUUID();
+	const originalPayload = occurrence === undefined ? undefined : JSON.stringify(occurrence.payload);
+	const payload =
+		occurrence === undefined
+			? initialFormValues(block.fields, {
+					[branch.identity]: identity,
+					[branch.discriminator]: block.slug,
+				})
+			: (cloneFormValue(occurrence.payload) as Record<string, unknown>);
+	const form = new FormController({ [id]: payload }, i18n, parent);
+	const fields = block.fields.map((child) => scopeRepeatedRowField(child, id, id));
+	const container: SchemaField = {
+		id,
+		name: id,
+		path: id,
+		type: "group",
+		category: "nested",
+		required: true,
+		unique: false,
+		admin: { label: block.labels.singular },
+		nested: { fields: block.fields },
+	};
+	form.reset({ [id]: payload }, [container]);
+	form.setResource(parent.resource);
+	const rebase = (path: string) =>
+		occurrence !== undefined && (path === occurrence.path || path.startsWith(`${occurrence.path}.`))
+			? id + path.slice(occurrence.path.length)
+			: path;
+	form.setAccess(
+		parent.access === undefined
+			? undefined
+			: {
+					...parent.access,
+					fields: Object.fromEntries(
+						Object.entries(parent.access.fields).map(([path, value]) => [rebase(path), value])
+					),
+				},
+		parent.accessMode
+	);
+	form.setLocalization(
+		locale,
+		Object.fromEntries(
+			Object.entries(parent.localizationSources).map(([path, value]) => [rebase(path), value])
+		)
+	);
+	const draftTargets = new Map(
+		indexFieldValues([container], form.snapshot()).map((location) => [
+			location.path,
+			location.token,
+		])
+	);
+	form.issues =
+		occurrence === undefined
+			? []
+			: parent.issues
+					.filter(
+						(issue) =>
+							issue.path === occurrence.path || issue.path.startsWith(`${occurrence.path}.`)
+					)
+					.map((issue) => {
+						const path = rebase(issue.path);
+						return {
+							...issue,
+							path,
+							...(issue.target === undefined ? {} : { target: draftTargets.get(path) }),
+						};
+					});
+	let discarded = false;
+	// Revocation is synchronous; UI notification waits until any derived read has finished.
+	let publishedDiscard = $state(false);
+	let invalidated = false;
+	const isStale = () =>
+		discarded ||
+		invalidated ||
+		!isActive() ||
+		parent.submitting ||
+		parent.revision !== revision ||
+		parent.contentLocale !== locale ||
+		accessState() !== initialAccess ||
+		JSON.stringify(getField().plugin?.embeddedTrees) !== signature ||
+		getField().admin.readOnly === true ||
+		!parent.canWrite(getField().path, fieldAccessPath(getField())) ||
+		(existing && JSON.stringify(findOccurrence()?.payload) !== originalPayload);
+	const stale = () => {
+		// A getter can run inside a Svelte derived expression. Record revocation without
+		// mutating reactive form state; retained child capabilities consult this scope.
+		if (isStale()) invalidated = true;
+		return invalidated;
+	};
+	form.setEditorScope(() => !stale());
+	if (parent.liveValidation.available) {
+		const relative = (path: string) => {
+			if (!path.startsWith(`${id}.`)) throw new Error("The embedded field is outside this draft.");
+			return path.slice(id.length + 1);
+		};
+		form.configureLiveValidation(async (input, signal) => {
+			if (stale()) throw new Error("This embedded schema draft is stale.");
+			const nested = input.embedded ?? [];
+			const data = input.data[id];
+			if (typeof data !== "object" || data === null || Array.isArray(data))
+				throw new Error("The embedded payload is unavailable.");
+			const result = await parent.requestLiveValidation(
+				{
+					...(parent.resource?.id === undefined ? {} : { id: parent.resource.id }),
+					data: parent.liveValidationData(),
+					fields: nested.length ? input.fields : input.fields.map(relative),
+					embedded: [
+						{
+							field: getField().path,
+							treeKey: variant.tree.key,
+							caseTag: branch.tagValue,
+							variantSlug: block.slug,
+							identity,
+							data: { ...data, [branch.identity]: identity, [branch.discriminator]: block.slug },
+						},
+						...nested.map((scope, index) =>
+							index === 0 ? { ...scope, field: relative(scope.field) } : scope
+						),
+					],
+				},
+				signal
+			);
+			// Only the innermost host rebases payload-relative feedback into its private form.
+			if (nested.length) return result;
+			const target = (value: string | undefined) => {
+				if (value === undefined) return undefined;
+				const canonical = canonicalIssueTarget(value);
+				return canonical === undefined ? undefined : JSON.stringify([id, ...JSON.parse(canonical)]);
+			};
+			return {
+				evaluations: result.evaluations.map((evaluation) => ({
+					...evaluation,
+					path: `${id}.${evaluation.path}`,
+					target: target(evaluation.target),
+					issues: evaluation.issues.map((issue) => ({
+						...issue,
+						path: `${id}.${issue.path}`,
+						target: target(issue.target),
+					})),
+				})),
+			};
+		});
+	}
+	const stop = parent.registerPendingEdit(() =>
+		discarded || !isActive() || (!form.dirty && existing)
+			? []
+			: [
+					{
+						code: "pending_embedded_edit",
+						path: getField().path,
+						message: i18n.t("errors:pendingEmbeddedEdit"),
+					},
+				]
+	);
+	const stopObserve = parent.observe(field.path.split(".")[0]!, () => {
+		if (stale()) form.disposeBindings();
+	});
+	const stopChanges = parent.observeChanges(() => {
+		if (stale()) form.disposeBindings();
+		else form.refreshLiveValidation();
+	});
+	const stopLifetime = parent.registerEditorLifetime(() => draft.discard());
+	const draft: EmbeddedSchemaDraft = {
+		id,
+		identity,
+		get dirty() {
+			return !publishedDiscard && !discarded && (form.dirty || !existing);
+		},
+		get stale() {
+			return publishedDiscard || stale();
+		},
+		get issues() {
+			return form.issues.map((issue) => ({ ...issue }));
+		},
+		payload: () => {
+			if (stale()) throw new Error("This embedded schema draft is stale.");
+			return cloneFormValue(form.get(id)) as Record<string, unknown>;
+		},
+		validate: () => {
+			form.liveValidation.suspend();
+			if (stale()) {
+				form.issues = [
+					{
+						code: "stale_embedded_edit",
+						path: id,
+						message: i18n.t("errors:staleEmbeddedEdit"),
+					},
+				];
+				return false;
+			}
+			form.issues = [
+				...form.pendingEditIssues(),
+				...validateFormValues([container], form.values, {
+					requireMissing: !existing,
+					include: (path, canonicalPath) =>
+						form.canRead(path, canonicalPath) && form.canWrite(path, canonicalPath),
+					i18n,
+				}),
+			];
+			return form.issues.length === 0;
+		},
+		discard: () => {
+			if (discarded) return;
+			discarded = true;
+			queueMicrotask(() => {
+				publishedDiscard = true;
+				stop();
+			});
+			stopObserve();
+			stopChanges();
+			stopLifetime();
+			form.disposeBindings();
+		},
+	};
+	return { draft, form, fields };
+}

package/src/core/forms/field-editor-authoring.ts

@@ -0,0 +1,47 @@
+import type { FieldAuthoringHost } from "@riducms/plugin";
+import type { FieldEditorProps } from "@riducms/plugin/editor";
+import { cloneFormValue } from "@admin/core/forms/form-schema";
+
+type EditorAuthoring = FieldEditorProps["authoring"];
+
+/** Stable callable identities, with invocation and async completion bound to one editor mount. */
+export function guardEditorAuthoring(
+	authoring: () => FieldAuthoringHost,
+	assertActive: () => void
+): EditorAuthoring {
+	const referenceBrowser: EditorAuthoring["referenceBrowser"] = (...args) => {
+		assertActive();
+		return authoring().referenceBrowser(...args);
+	};
+	const findDocument: EditorAuthoring["findDocument"] = (...args) => {
+		assertActive();
+		return authoring()
+			.findDocument(...args)
+			.then((document) => {
+				assertActive();
+				return document;
+			});
+	};
+	return {
+		get collections() {
+			assertActive();
+			return cloneFormValue(authoring().collections) as EditorAuthoring["collections"];
+		},
+		get documentRevision() {
+			assertActive();
+			return authoring().documentRevision;
+		},
+		get locale() {
+			assertActive();
+			return authoring().locale;
+		},
+		get referenceBrowser() {
+			assertActive();
+			return referenceBrowser;
+		},
+		get findDocument() {
+			assertActive();
+			return findDocument;
+		},
+	};
+}

package/src/core/forms/field-editor-binding.ts

@@ -0,0 +1,228 @@
+import { cloneSchemaField } from "@riducms/protocol";
+import type {
+	FieldBinding,
+	FieldEditorProps,
+	FieldEditorType,
+	FieldEditorValue,
+} from "@riducms/plugin/editor";
+import type { SchemaField } from "@riducms/protocol";
+import { fieldControlARIA } from "@riducms/ui";
+import type { FormController } from "@admin/core/forms/form-controller.svelte";
+import { fieldAccessPath } from "@admin/fields/nested/scoped-field";
+import { cloneFormValue } from "@admin/core/forms/form-schema";
+import { evaluateFieldCondition } from "@admin/core/forms/field-condition";
+import { captureFieldOccurrence, type FieldOccurrence } from "@admin/core/forms/field-occurrence";
+
+/** The host owns this capability until unmount or an invalidating form transition. */
+export class FieldEditorBinding<Type extends FieldEditorType> implements FieldBinding<Type> {
+	#form: FormController;
+	#schema: () => SchemaField;
+	#occurrence: FieldOccurrence;
+	#path: string;
+	#stale = false;
+	#stopPath: () => void;
+	#stopObserve: () => void;
+	#stopLifetime: () => void;
+	#epoch: number;
+	#resource: string;
+	#locale: string | undefined;
+	#type: Type;
+	#schemaID: string;
+	#schemaVersion: () => unknown;
+	#initialSchemaVersion: unknown;
+	readonly form: FieldEditorProps["form"];
+
+	constructor(
+		form: FormController,
+		schema: () => SchemaField,
+		type: Type,
+		schemaVersion: () => unknown = () => form.editorEpoch
+	) {
+		this.#form = form;
+		this.#schemaID = schema().id;
+		this.#schemaVersion = schemaVersion;
+		this.#initialSchemaVersion = schemaVersion();
+		this.#schema = schema;
+		this.#type = type;
+		this.#epoch = form.editorEpoch;
+		this.#resource = JSON.stringify(form.resource);
+		this.#locale = form.contentLocale;
+		this.#path = schema().path;
+		this.#occurrence = captureFieldOccurrence(form, this.#path);
+		this.#stopPath = form.register(this.#path);
+		this.#stopObserve = form.observe(this.#path.split(".")[0]!, () => this.#resolve());
+		this.#stopLifetime = form.registerEditorLifetime(this.destroy);
+		const binding = this;
+		this.form = {
+			get contentLocale() {
+				binding.assertActive();
+				return binding.#locale;
+			},
+			get resource() {
+				binding.assertActive();
+				return form.resource === undefined ? undefined : { ...form.resource };
+			},
+			get: (path) => {
+				this.assertActive();
+				return cloneFormValue(form.get(path));
+			},
+			issuesFor: (path) => {
+				this.assertActive();
+				return form.issuesFor(path).map((issue) => ({ ...issue }));
+			},
+			snapshot: () => {
+				this.assertActive();
+				return form.snapshot();
+			},
+		};
+	}
+
+	get schema(): SchemaField & { type: Type } {
+		// A revoked host can render once before its keyed subtree unmounts. Metadata
+		// remains a detached snapshot; values and writes stay revoked immediately.
+		this.#resolve();
+		return {
+			...cloneSchemaField(this.#schema()),
+			type: this.#type,
+			path: this.#path,
+		};
+	}
+	get stale() {
+		this.#resolve();
+		return this.#stale;
+	}
+	get value(): FieldEditorValue<Type> | null | undefined {
+		if (this.stale) return undefined;
+		const value = this.#form.get(this.#path);
+		assertEditorValue(this.#type, value);
+		return cloneFormValue(value) as FieldEditorValue<Type> | null | undefined;
+	}
+	get issues() {
+		return this.stale ? [] : this.#form.issuesFor(this.#path).map((issue) => ({ ...issue }));
+	}
+	get liveValidation() {
+		if (this.stale) return { status: "idle" as const, retry: () => {} };
+		const feedback = this.#form.liveValidation.forField(this.#path);
+		return {
+			status: feedback.status,
+			retry: () => {
+				this.assertActive();
+				if (!this.readOnly) this.#form.liveValidation.flush(this.#path);
+			},
+		};
+	}
+
+	get readOnly() {
+		if (this.stale) return true;
+		if (
+			this.#occurrence.ancestors.some(({ schema, resolve }) => {
+				const path = resolve();
+				return (
+					path === undefined ||
+					schema.admin.readOnly === true ||
+					schema.admin.hidden === true ||
+					!this.#form.canRead(path, fieldAccessPath(schema)) ||
+					!this.#form.canWrite(path, fieldAccessPath(schema)) ||
+					(schema.admin.condition !== undefined &&
+						!evaluateFieldCondition(schema.admin.condition, path, (other) => this.#form.get(other)))
+				);
+			})
+		)
+			return true;
+		const schema = this.#schema();
+		const accessPath = fieldAccessPath(schema);
+		return (
+			this.#form.editingBlocked ||
+			schema.admin.readOnly === true ||
+			schema.admin.hidden === true ||
+			!this.#form.canRead(this.#path, accessPath) ||
+			!this.#form.canWrite(this.#path, accessPath) ||
+			(schema.admin.condition !== undefined &&
+				!evaluateFieldCondition(schema.admin.condition, this.#path, (path) => this.#form.get(path)))
+		);
+	}
+	get inputProps() {
+		const schema = this.schema;
+		const invalid = this.issues.length > 0;
+		return {
+			id: schema.id,
+			name: schema.path,
+			// Native required checks one input. Boolean false and list items containing empty
+			// strings can satisfy their Ridu field; their container rule runs on submit.
+			required:
+				this.#type !== "checkbox" &&
+				this.#type !== "text-list" &&
+				this.#type !== "number-list" &&
+				schema.required &&
+				(!schema.dynamicDefault || this.value !== undefined),
+			...fieldControlARIA(schema.id, schema.admin.description !== undefined, invalid),
+		};
+	}
+	set = (value: FieldEditorValue<Type> | null) => {
+		this.#write(value);
+	};
+	assertActive = () => {
+		if (this.stale)
+			throw new Error(
+				"This field editor is stale. Use the editor mounted for the current document, locale and field occurrence."
+			);
+	};
+	destroy = () => {
+		if (this.#stale) return;
+		this.#stale = true;
+		this.#stopPath();
+		this.#stopObserve();
+		this.#stopLifetime();
+	};
+	#write(value: unknown) {
+		this.assertActive();
+		if (this.readOnly) throw new Error(`Field ${this.#path} is read-only.`);
+		assertEditorValue(this.#type, value);
+		if (value === undefined) throw new Error("Use null to clear an editor value.");
+		this.#form.set(this.#path, cloneFormValue(value));
+	}
+	#resolve() {
+		if (this.#stale) return;
+		if (
+			this.#schema().id !== this.#schemaID ||
+			this.#schemaVersion() !== this.#initialSchemaVersion ||
+			!this.#form.editorScopeActive ||
+			this.#form.editorEpoch !== this.#epoch ||
+			this.#form.contentLocale !== this.#locale ||
+			JSON.stringify(this.#form.resource) !== this.#resource
+		) {
+			this.destroy();
+			return;
+		}
+		const path = this.#occurrence.resolve();
+		if (path === undefined) {
+			this.destroy();
+			return;
+		}
+		if (path !== this.#path) {
+			this.#stopPath();
+			this.#path = path;
+			this.#stopPath = this.#form.register(path);
+		}
+	}
+}
+
+function assertEditorValue(type: FieldEditorType, value: unknown) {
+	if (value === null || value === undefined) return;
+	if (type === "text-list" || type === "number-list") {
+		const element = type === "text-list" ? "string" : "number";
+		if (
+			!Array.isArray(value) ||
+			!Array.from(value).every(
+				(item) => typeof item === element && (element !== "number" || Number.isFinite(item))
+			)
+		)
+			throw new Error(
+				`Editor for ${type} expected an array of ${element}s with no null or invalid items.`
+			);
+		return;
+	}
+	const expected = type === "number" ? "number" : type === "checkbox" ? "boolean" : "string";
+	if (typeof value !== expected || (typeof value === "number" && !Number.isFinite(value)))
+		throw new Error(`Editor for ${type} expected a ${expected} value or null.`);
+}

package/src/core/forms/field-issue-focus.ts

@@ -0,0 +1,42 @@
+import { tick } from "svelte";
+
+export const fieldIssueRevealEvent = "ridu:reveal-field-issue";
+
+/** Open lazy field disclosures and repeated rows before focusing the invalid control. */
+export async function focusFieldIssue(path: string) {
+	const selector = `[data-field-path="${CSS.escape(path)}"]`;
+	let previous: HTMLElement | null = null;
+	// Each reveal can mount the next schema boundary. Bound the search by the
+	// path depth, and stop when a reveal no longer makes progress.
+	for (let depth = 0; depth <= path.split(".").length; depth++) {
+		const segments = path.split(".");
+		let container: HTMLElement | null = null;
+		while (segments.length > 0 && container === null) {
+			container = document.querySelector<HTMLElement>(
+				`[data-field-path="${CSS.escape(segments.join("."))}"]`
+			);
+			segments.pop();
+		}
+		if (container === null || container === previous) return;
+		previous = container;
+		for (
+			let ancestor = container.parentElement;
+			ancestor !== null;
+			ancestor = ancestor.parentElement
+		) {
+			if (ancestor instanceof HTMLDetailsElement && ancestor.hasAttribute("data-field-collapsible"))
+				ancestor.open = true;
+		}
+		container.dispatchEvent(new Event(fieldIssueRevealEvent, { bubbles: true }));
+		await tick();
+		const revealed = document.querySelector<HTMLElement>(selector);
+		const control = revealed?.querySelector<HTMLElement>(
+			"input:not([disabled]), textarea:not([disabled]), [contenteditable='true'], button:not([disabled]), [tabindex]:not([tabindex='-1'])"
+		);
+		if (revealed !== null && control != null) {
+			revealed.scrollIntoView({ behavior: "instant", block: "center" });
+			control.focus({ preventScroll: true });
+			return;
+		}
+	}
+}