@riducms/plugin 0.2.0 → 0.2.2

package/README.md

@@ -259,6 +259,26 @@ tree, and `identity` identifies the existing item. Ridu finds its current positi
 ordinary fields. Edits immediately enter the parent form; this does not save the document.
 Removed/malformed items show recovery UI rather than another item's fields.
 
+For a Go-configured `BlockAdmin.NameField`, `schemaHeader` renders just the editorial
+name input and its feedback:
+
+```svelte
+{#if authoring.schemaHeader !== undefined}
+  {@render authoring.schemaHeader({
+    treeKey: "widgets",
+    identity: selectedIdentity,
+    onChange: ({ field, value }) => updateWidgetField(selectedIdentity, field, value),
+  })}
+{/if}
+```
+
+Here `updateWidgetField` belongs to your plugin: apply the permitted field change
+to the latest matching item through your editor's history, then serialize with
+`field.set`. The header does not directly change the parent form. Ridu resolves the
+configured child, checks its access and visibility, and disables the card header
+while a draft for that tree and identity is open. The ordinary content renderer
+omits the name field's body placement; draft drawers include it in their own header.
+
 For **Apply/Cancel**, use a temporary embedded draft:
 
 1. Call `beginSchemaDraft({ treeKey, identity })` for an existing item, or

package/package.json

@@ -3,9 +3,9 @@
 		"url": "https://github.com/riducms/ridu/issues"
 	},
 	"dependencies": {
-		"@riducms/protocol": "0.2.0",
-		"@riducms/translations": "0.2.0",
-		"@riducms/ui": "0.2.0"
+		"@riducms/protocol": "0.2.2",
+		"@riducms/translations": "0.2.2",
+		"@riducms/ui": "0.2.2"
 	},
 	"description": "Public TypeScript contracts for statically registered Ridu admin plugins.",
 	"exports": {
@@ -39,5 +39,5 @@
 		"test": "bun test"
 	},
 	"type": "module",
-	"version": "0.2.0"
+	"version": "0.2.2"
 }

package/src/admin.ts

@@ -1,15 +1,25 @@
 import { bindSchemaManifest } from "@riducms/protocol";
 import { resolveBlockTypes } from "@riducms/protocol";
-import { validatePluginManifest, validatePluginRegistrations } from "./plugin-registry";
+import {
+	resolvePluginFields,
+	validateManifestPluginPairs,
+	createPluginFieldValidator,
+	type ResolvedPluginField,
+} from "./plugin-registry";
 import { isRegisteredRowLabel, type RegisteredRowLabel } from "./local-row-label";
 import { localEditorReference } from "./editor/registry";
 import type { SchemaField } from "@riducms/protocol";
 import type { SchemaManifest } from "@riducms/protocol";
-import type { TranslationLanguage } from "@riducms/translations";
+import { en, type TranslationLanguage } from "@riducms/translations";
 import type { PluginMessageCatalog } from "./i18n";
-import { resolveAdminExtensions, type AdminContributions, type AdminPlugin } from "./plugin";
 import {
-	validateAdminEditors,
+	resolveAdminExtensions,
+	type AdminContributions,
+	type AdminPlugin,
+	type ResolvedAdminExtensions,
+} from "./plugin";
+import {
+	validateFieldEditorSelection,
 	validateFieldEditorRegistrations,
 	type FieldEditorConfig,
 } from "./editor/registry";
@@ -50,9 +60,8 @@ export interface AdminConfig extends AdminContributions, FieldEditorConfig {
  * These checks also run when building and starting the admin.
  *
  * @param config The installed plugins, custom components, and interface translations.
- * @returns The same configuration object after registration checks. The admin
+ * @returns The same typed configuration object. The admin
  * reads it when starting; calling this function does not mount any components.
- * @throws If registrations, keys, or replacement locations conflict.
  * @example
  * ```ts
  * import { defineAdmin } from '@riducms/plugin/admin';
@@ -66,18 +75,39 @@ export interface AdminConfig extends AdminContributions, FieldEditorConfig {
  * ```
  */
 export function defineAdmin(config: AdminConfig): AdminConfig {
+	return config;
+}
+
+/** Static configuration owned by one mounted admin. Changes require remount/HMR. */
+export interface ResolvedAdminConfig {
+	readonly plugins: readonly AdminPlugin[];
+	readonly fields: readonly ResolvedPluginField[];
+	readonly editors: NonNullable<AdminConfig["fields"]>;
+	readonly rowLabels: NonNullable<AdminConfig["rowLabels"]>;
+	readonly languages: readonly TranslationLanguage[];
+	readonly extensions: Readonly<ResolvedAdminExtensions>;
+}
+
+/** Normalize and validate static registrations once, independently of schema refresh. */
+export function resolveAdminConfig(config: AdminConfig = {}): ResolvedAdminConfig {
 	if ("fieldPlugins" in config)
 		throw new Error(
 			"Application fieldPlugins are not supported; use a field-owned Editor component or a paired advanced field plugin."
 		);
-	validatePluginRegistrations(config.plugins ?? []);
 	validateFieldEditorRegistrations(config);
 	for (const [reference, label] of Object.entries(config.rowLabels ?? {})) {
 		if (!localEditorReference.test(reference) || !isRegisteredRowLabel(label))
 			throw new Error(`Row label ${reference} must use an app:name reference and defineRowLabel.`);
 	}
-	resolveAdminExtensions(config.plugins ?? [], config);
-	return config;
+	const plugins = Object.freeze([...(config.plugins ?? [])]);
+	return Object.freeze({
+		plugins,
+		fields: resolvePluginFields(plugins),
+		editors: Object.freeze({ ...config.fields }),
+		rowLabels: Object.freeze({ ...config.rowLabels }),
+		languages: Object.freeze(config.languages?.length ? [...config.languages] : [en]),
+		extensions: Object.freeze(resolveAdminExtensions(plugins, config)),
+	});
 }
 
 /**
@@ -87,40 +117,47 @@ export function defineAdmin(config: AdminConfig): AdminConfig {
  * resources the current user cannot access, so absence there does not prove a typo.
  * Throws with the affected registration or field when a selection/config is invalid.
  */
-export function validateAdminConfig(
-	config: AdminConfig,
+export function validateAdminManifest(
+	config: ResolvedAdminConfig,
 	manifest: Pick<SchemaManifest, "collections" | "globals" | "blocks"> &
 		Partial<Pick<SchemaManifest, "plugins">>,
 	options: { completeManifest?: boolean } = {}
 ): void {
-	defineAdmin(config);
-	validateAdminEditors(config, manifest);
-	validatePluginManifest(config.plugins ?? [], manifest, options.completeManifest === true);
+	validateManifestPluginPairs(
+		config.plugins,
+		config.fields,
+		manifest,
+		options.completeManifest === true
+	);
+	const validatePluginField = createPluginFieldValidator(config.fields);
+	const failures: string[] = [];
 	bindSchemaManifest(manifest);
 	const inspect = (fields: readonly SchemaField[], owner: string) => {
 		for (const field of fields) {
-			const selection = field.nested?.rowLabelComponent;
-			if (selection?.reference !== undefined) {
-				const reference = selection.reference;
-				if (
-					!localEditorReference.test(reference) ||
-					selection.plugin !== undefined ||
-					selection.component !== undefined ||
-					(field.type !== "array" && field.type !== "blocks")
-				)
-					throw new Error(`${owner}.${field.path}: invalid local row label selection.`);
-				const label = config.rowLabels?.[reference as `app:${string}`];
-				if (label === undefined)
-					throw new Error(
-						`${owner}.${field.path}: row label ${reference} is not registered in admin/src/admin.config.ts.`
-					);
-				try {
+			try {
+				validateFieldEditorSelection(config.editors, field);
+				validatePluginField(field);
+				const selection = field.nested?.rowLabelComponent;
+				if (selection?.reference !== undefined) {
+					const reference = selection.reference;
+					if (
+						!localEditorReference.test(reference) ||
+						selection.plugin !== undefined ||
+						selection.component !== undefined ||
+						(field.type !== "array" && field.type !== "blocks")
+					)
+						throw new Error("invalid local row label selection.");
+					const label = config.rowLabels?.[reference as `app:${string}`];
+					if (label === undefined)
+						throw new Error(
+							`row label ${reference} is not registered in admin/src/admin.config.ts.`
+						);
 					label.decode(field);
-				} catch (error) {
-					throw new Error(
-						`${owner}.${field.path}: ${error instanceof Error ? error.message : String(error)}`
-					);
 				}
+			} 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)
@@ -131,11 +168,12 @@ export function validateAdminConfig(
 	};
 	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) throw new Error(failures.join("\n"));
 	// Runtime manifests are permission-filtered; only build checks can prove target absence.
 	if (!options.completeManifest) return;
 	const collections = new Map(manifest.collections.map((item) => [item.slug, item]));
 	const globals = new Set((manifest.globals ?? []).map((item) => item.slug));
-	const extensions = resolveAdminExtensions(config.plugins ?? [], config);
+	const extensions = config.extensions;
 	for (const cell of extensions.listCells) {
 		const collection = collections.get(cell.collection);
 		if (!collection?.fields.some((field) => field.name === cell.field || field.path === cell.field))

package/src/authoring/v1.ts

@@ -1,5 +1,5 @@
 import type { AdminPlugin } from "../plugin";
-import { validatePluginRegistrations } from "../plugin-registry";
+import { resolvePluginFields } from "../plugin-registry";
 
 export { definePluginField, defineFieldComponent } from "../field";
 export type {
@@ -66,6 +66,6 @@ export function defineAdminPlugin<const Plugin extends Omit<AdminPlugin, "apiVer
 		apiVersion: authoringAPIVersion,
 	});
 	const definition: Omit<AdminPlugin, "apiVersion"> = plugin;
-	validatePluginRegistrations([{ ...definition, apiVersion: authoringAPIVersion }]);
+	resolvePluginFields([{ ...definition, apiVersion: authoringAPIVersion }]);
 	return result;
 }

package/src/authoring.ts

@@ -84,6 +84,16 @@ export interface EmbeddedSchemaFormScope {
 	readOnly?: boolean;
 }
 
+/** A configured editorial-name control for one existing embedded item. */
+export interface EmbeddedSchemaHeaderProps extends EmbeddedSchemaFormScope {
+	/**
+	 * Receives a permitted change to the Go-configured name field. Apply it to the
+	 * latest matching item through your editor's own history/serialization path.
+	 * The host does not write the parent form or save the document itself.
+	 */
+	onChange: (change: { field: string; value: string }) => void;
+}
+
 /** 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. */
@@ -159,6 +169,12 @@ export interface FieldAuthoringHost {
 	 * if the user needs Apply/Cancel. Neither approach saves the document itself.
 	 */
 	schemaForm?: Snippet<[EmbeddedSchemaFormScope]>;
+	/**
+	 * Render the configured name input and field feedback, without the card chrome.
+	 * Uses the item's schema, access, visibility and stable identity. An open draft
+	 * locks the card input; an item without a name field renders no control.
+	 */
+	schemaHeader?: Snippet<[EmbeddedSchemaHeaderProps]>;
 	/**
 	 * Start a temporary Apply/Cancel form. Pass `{ treeKey, identity }` to edit an
 	 * existing item, or `{ treeKey, caseTag, variantSlug }` to prepare a new one using

package/src/editor/registry.ts

@@ -1,7 +1,5 @@
-import { bindSchemaManifest } from "@riducms/protocol";
-import { resolveBlockTypes } from "@riducms/protocol";
 import type { Component } from "svelte";
-import type { SchemaField, SchemaManifest } from "@riducms/protocol";
+import type { SchemaField } from "@riducms/protocol";
 
 import type { FieldEditorProps, FieldEditorType } from "./types";
 import { decodeComponentConfig } from "../component-config";
@@ -134,41 +132,19 @@ export function validateFieldEditorRegistrations(config: FieldEditorConfig): voi
 	}
 }
 
-/** Uses the same executable registrations and decoders in the browser and build checks. */
-export function validateAdminEditors(
-	config: FieldEditorConfig,
-	manifest: Pick<SchemaManifest, "collections" | "globals" | "blocks">
+/** Check one local selection using the same decoder as the mounted editor. */
+export function validateFieldEditorSelection(
+	editors: NonNullable<FieldEditorConfig["fields"]>,
+	field: SchemaField
 ): 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"));
+	const reference = field.admin.editor?.reference;
+	if (reference === undefined) return;
+	if (!localEditorReference.test(reference))
+		throw new Error(`Malformed editor reference ${reference}; expected app:name.`);
+	const editor = editors[reference as `app:${string}`];
+	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);
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 export type {
 	EmbeddedSchemaFormScope,
+	EmbeddedSchemaHeaderProps,
 	EmbeddedSchemaVariantScope,
 	EmbeddedSchemaDraft,
 	EmbeddedSchemaDraftEditorProps,
@@ -36,7 +37,7 @@ export {
 export {
 	ADMIN_PLUGIN_API_VERSION,
 	resolveAdminExtensions,
-	resolveAdminPluginPairs,
+	assertAdminPluginPairs,
 	type AdminPlugin,
 	type AdminContributions,
 	type AdminDashboardPanel,
@@ -79,7 +80,6 @@ export {
 	type AdminRoute,
 	type BackendAdminPlugin,
 	type ResolvedAdminExtensions,
-	type ResolvedAdminPluginPairs,
 } from "./plugin";
 
 export { resolvePluginFields, type ResolvedPluginField } from "./plugin-registry";

package/src/plugin-registry.ts

@@ -1,8 +1,6 @@
-import { bindSchemaManifest } from "@riducms/protocol";
-import { resolveBlockTypes } from "@riducms/protocol";
 import { ADMIN_PLUGIN_API_VERSION, type SchemaField, type SchemaManifest } from "@riducms/protocol";
 import { assertPluginFieldRegistration, type RegisteredPluginField } from "./field";
-import type { AdminPlugin } from "./plugin";
+import { assertAdminPluginPairs, type AdminPlugin } from "./plugin";
 
 /** A registered field editor with the names Ridu uses to select it. Returned by registry resolution. */
 export interface ResolvedPluginField {
@@ -15,10 +13,6 @@ export interface ResolvedPluginField {
 	readonly registration: RegisteredPluginField;
 }
 
-export function validatePluginRegistrations(plugins: readonly AdminPlugin[]): void {
-	resolvePluginFields(plugins);
-}
-
 /**
  * Collect field registrations, checking plugin IDs, field-type ownership, named
  * components and API versions. Throws on malformed/duplicate registrations.
@@ -87,13 +81,13 @@ export function resolvePluginFields(
 }
 
 /** Canonical manifest, actual executable registrations, and the same decoders as the host. */
-export function validatePluginManifest(
+export function validateManifestPluginPairs(
 	plugins: readonly AdminPlugin[],
+	registrations: readonly ResolvedPluginField[],
 	manifest: Pick<SchemaManifest, "collections" | "globals" | "blocks"> &
 		Partial<Pick<SchemaManifest, "plugins">>,
 	complete: boolean
 ): void {
-	const registrations = resolvePluginFields(plugins);
 	// Startup may receive only public or access-filtered schemas. Build/check own
 	// completeness; selected fields below still validate their exact renderer.
 	if (complete && manifest.plugins !== undefined)
@@ -108,38 +102,22 @@ export function validatePluginManifest(
 					`Named renderer ${item.owner}:${item.key} selects undeclared field type ${item.registration.fieldType}.`
 				);
 		}
-	const fields = new Map(
-		registrations.filter((item) => item.componentKey === undefined).map((item) => [item.key, item])
-	);
-	const components = new Map(
-		registrations
-			.filter((item) => item.componentKey !== undefined)
-			.map((item) => [`${item.owner}:${item.key}`, item])
-	);
 	if (manifest.plugins !== undefined) {
 		for (const backend of manifest.plugins) {
 			if (backend.admin === undefined) continue;
 			const plugin = plugins.find((candidate) => candidate.key === backend.key);
 			if (plugin === undefined)
 				throw new Error(`Missing admin registration for backend plugin ${backend.key}.`);
-			if (
-				plugin.apiVersion !== backend.admin.apiVersion ||
-				plugin.pairingVersion !== backend.admin.pairingVersion
-			)
-				throw new Error(`Backend/admin compatibility mismatch for plugin ${backend.key}.`);
-			if (
-				JSON.stringify(backend.admin.routes ?? []) !==
-					JSON.stringify((plugin.routes ?? []).map((route) => route.path)) ||
-				JSON.stringify(backend.admin.assets ?? []) !== JSON.stringify(plugin.assets ?? [])
-			)
-				throw new Error(
-					`Plugin ${backend.key} routes/assets do not match the canonical Go descriptor.`
-				);
-			const expected = (backend.fieldTypes ?? []).map((field) => field.key).sort();
-			if (JSON.stringify(expected) !== JSON.stringify(Object.keys(plugin.fields ?? {}).sort()))
-				throw new Error(
-					`Plugin ${backend.key} field types do not match the canonical Go descriptor (${expected.join(", ")}).`
-				);
+			assertAdminPluginPairs([
+				{
+					admin: plugin,
+					backend: {
+						...backend.admin,
+						key: backend.key,
+						fieldTypes: (backend.fieldTypes ?? []).map((field) => field.key),
+					},
+				},
+			]);
 		}
 		if (complete)
 			for (const plugin of plugins) {
@@ -151,38 +129,32 @@ export function validatePluginManifest(
 					throw new Error(`Admin plugin ${plugin.key} has no paired Go admin descriptor.`);
 			}
 	}
-	const failures: string[] = [];
-	bindSchemaManifest(manifest);
-	const inspect = (items: readonly SchemaField[], owner: string) => {
-		for (const field of items) {
-			try {
-				const selection = field.admin.component;
-				const selected =
-					selection !== undefined
-						? components.get(`${selection.plugin}:${selection.component}`)
-						: field.type === "plugin"
-							? fields.get(field.plugin?.key ?? "")
-							: undefined;
-				if (selection !== undefined || field.type === "plugin") {
-					if (selected === undefined)
-						throw new Error(
-							`Missing renderer for ${selection !== undefined ? `${selection.plugin}:${selection.component}` : field.plugin?.key}.`
-						);
-					selected.registration.decodeConfig(field);
-				}
-			} catch (error) {
-				failures.push(
-					`${owner}.${field.path}: ${error instanceof Error ? error.message : String(error)}`
+}
+
+/** Resolve a selection against static registrations; the caller owns schema traversal. */
+export function createPluginFieldValidator(registrations: readonly ResolvedPluginField[]) {
+	const fields = new Map(
+		registrations.filter((item) => item.componentKey === undefined).map((item) => [item.key, item])
+	);
+	const components = new Map(
+		registrations
+			.filter((item) => item.componentKey !== undefined)
+			.map((item) => [`${item.owner}:${item.key}`, item])
+	);
+	return (field: SchemaField): void => {
+		const selection = field.admin.component;
+		const selected =
+			selection !== undefined
+				? components.get(`${selection.plugin}:${selection.component}`)
+				: field.type === "plugin"
+					? fields.get(field.plugin?.key ?? "")
+					: undefined;
+		if (selection !== undefined || field.type === "plugin") {
+			if (selected === undefined)
+				throw new Error(
+					`Missing renderer for ${selection !== undefined ? `${selection.plugin}:${selection.component}` : field.plugin?.key}.`
 				);
-			}
-			if (field.nested !== undefined) inspect(field.nested.fields, owner);
-			for (const block of resolveBlockTypes(field.blocks) ?? []) inspect(block.fields, owner);
-			for (const tree of field.plugin?.embeddedTrees ?? [])
-				for (const branch of tree.cases)
-					for (const block of resolveBlockTypes(branch)) inspect(block.fields, owner);
+			selected.registration.decodeConfig(field);
 		}
 	};
-	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) throw new Error(failures.join("\n"));
 }

package/src/plugin.ts

@@ -1,6 +1,5 @@
 import type { FieldType } from "@riducms/protocol";
 import type { RegisteredPluginField } from "./field";
-import { resolvePluginFields, type ResolvedPluginField } from "./plugin-registry";
 import { ADMIN_PLUGIN_API_VERSION } from "@riducms/protocol";
 import type {
 	OperationCapabilities,
@@ -402,9 +401,7 @@ export interface AdminPluginPair {
 }
 
 /** Checked plugin registrations collected for Ridu's admin runtime. Normally consumed by generated code. */
-export interface ResolvedAdminPluginPairs {
-	plugins: readonly AdminPlugin[];
-	fields: readonly ResolvedPluginField[];
+export interface ResolvedAdminExtensions {
 	rowLabels: readonly RowLabelPlugin[];
 	routes: readonly AdminRoute[];
 	dashboard: readonly AdminDashboardPanel[];
@@ -423,19 +420,14 @@ export interface ResolvedAdminPluginPairs {
 	applicationMessages: PluginMessageCatalog | undefined;
 }
 
-export type ResolvedAdminExtensions = Omit<ResolvedAdminPluginPairs, "plugins" | "fields">;
-
 /**
  * Check that installed Go/admin plugin packages agree on identity, API version,
  * pairing version, routes, assets and field types. Ridu's generated file calls this;
  * authors should fix mismatched packages rather than editing generated metadata.
  * Missing imports fail during compilation; incompatible pairs throw here.
  */
-export function resolveAdminPluginPairs(
-	pairs: readonly AdminPluginPair[]
-): ResolvedAdminPluginPairs {
+export function assertAdminPluginPairs(pairs: readonly AdminPluginPair[]): void {
 	const keys = new Set<string>();
-	const plugins: AdminPlugin[] = [];
 
 	for (const { admin, backend } of pairs) {
 		const identity = `${backend.package}#${backend.export}`;
@@ -473,15 +465,7 @@ export function resolveAdminPluginPairs(
 			Object.keys(admin.fields ?? {}).sort()
 		);
 		keys.add(backend.key);
-		plugins.push(admin);
 	}
-	const extensions = resolveAdminExtensions(plugins);
-
-	return {
-		plugins: Object.freeze(plugins),
-		fields: resolvePluginFields(plugins),
-		...extensions,
-	};
 }
 
 /**