@riducms/plugin 0.1.5 → 0.2.0

package/src/i18n.ts

@@ -2,6 +2,7 @@ import type {
 	AdminI18n,
 	PluginMessageCatalog,
 	PluginTranslationKey,
+	ExtensionTranslationKey,
 	TranslationMessage,
 } from "@riducms/translations";
 import { validatePluginMessageCatalog } from "@riducms/translations";
@@ -67,11 +68,21 @@ type CheckedAdminMessages<Input extends AdminMessagesShape> =
 export interface DefineAdminMessagesInput<
 	Fallback extends Readonly<Record<string, TranslationMessage>>,
 > {
+	/** Default text for every message key. Keys here do not include the plugin/app namespace. */
 	fallback: Fallback;
+	/** Catalogs by language code; each supplied language must translate every fallback key. */
 	translations?: Readonly<Record<string, ExactCatalog<Fallback>>>;
 }
 
-/** Defines one plugin-owned message catalog with exact translated key coverage. */
+/**
+ * Define interface text for a plugin or application. Every supplied translation
+ * must have the fallback catalog's keys, message kinds and `{placeholder}` names.
+ * The helper checks and freezes the catalogs; literals also receive TypeScript checks.
+ *
+ * For plugin key `"notes"`, fallback key `"copy"` is read as
+ * `i18n.t("plugin.notes:copy")`. In `defineAdmin({ messages })`, it is `"app:copy"`.
+ * These are admin interface translations, not translations of saved content.
+ */
 export function defineAdminMessages<const Input extends AdminMessagesShape>(
 	input: Input & CheckedAdminMessages<Input>
 ): DefineAdminMessagesInput<Input["fallback"]> {
@@ -79,6 +90,7 @@ export function defineAdminMessages<const Input extends AdminMessagesShape>(
 	return freezeAdminMessages(input) as DefineAdminMessagesInput<Input["fallback"]>;
 }
 
+/** Check a catalog at runtime, throwing with its owner key on invalid messages/translations. */
 export function validateAdminMessages(key: string, messages: PluginMessageCatalog) {
 	validatePluginMessageCatalog(key, messages);
 }
@@ -91,7 +103,20 @@ export function freezeAdminMessages(messages: PluginMessageCatalog): PluginMessa
 	return Object.freeze(messages);
 }
 
-const [getAdminI18n, setAdminI18n] = createContext<AdminI18n>();
+// Separate named exports let TypeScript show their docs at call sites; these remain the same functions.
+const [readAdminI18n, provideAdminI18n] = createContext<AdminI18n>();
 
-export { getAdminI18n, setAdminI18n };
-export type { AdminI18n, PluginMessageCatalog, PluginTranslationKey };
+/**
+ * Read Ridu's translation context during Svelte component setup. Field/extension
+ * components already receive `i18n` in props; nested components can use this getter.
+ * Throws outside a provider, such as a standalone component test without context.
+ */
+export const getAdminI18n = readAdminI18n;
+
+/**
+ * Provide translations to child components during Svelte component setup.
+ * Ridu normally does this. Use it when hosting components independently, for
+ * example in a test that needs to supply its own AdminI18n instance.
+ */
+export const setAdminI18n = provideAdminI18n;
+export type { AdminI18n, PluginMessageCatalog, PluginTranslationKey, ExtensionTranslationKey };

package/src/index.ts

@@ -1,10 +1,20 @@
 export type {
+	EmbeddedSchemaFormScope,
+	EmbeddedSchemaVariantScope,
+	EmbeddedSchemaDraft,
+	EmbeddedSchemaDraftEditorProps,
 	FieldAuthoringHost,
 	FieldDocument,
 	FieldReferenceBrowserProps,
 	FieldReferenceFilter,
 } from "./authoring";
-export { defineFieldPlugin, type FieldComponentProps, type FieldPlugin } from "./field";
+export type {
+	PluginFieldBinding,
+	PluginFieldProps,
+	PluginForm,
+	RegisteredPluginField,
+	PluginFieldRegistration,
+} from "./field";
 export {
 	defineRowLabelPlugin,
 	type RowLabelComponentProps,
@@ -12,7 +22,7 @@ export {
 	type RowLabelSnapshot,
 	type RowLabelValue,
 } from "./row-label";
-export type { FieldForm, FieldFormResource } from "./form";
+export type { FieldDocumentForm, FieldFormResource, FieldLiveValidation } from "./form";
 export {
 	defineAdminMessages,
 	getAdminI18n,
@@ -25,10 +35,10 @@ export {
 } from "./i18n";
 export {
 	ADMIN_PLUGIN_API_VERSION,
-	defineAdminPlugin,
-	resolveAdminPluginExtensions,
+	resolveAdminExtensions,
 	resolveAdminPluginPairs,
 	type AdminPlugin,
+	type AdminContributions,
 	type AdminDashboardPanel,
 	type AdminDashboardPanelProps,
 	type AdminExtensionProps,
@@ -64,10 +74,12 @@ export {
 	type AdminExtensionNotificationTone,
 	type AdminListCell,
 	type AdminListCellProps,
-	type AdminPluginNavigation,
+	type AdminRouteNavigation,
 	type AdminPluginPair,
-	type AdminPluginRoute,
+	type AdminRoute,
 	type BackendAdminPlugin,
-	type ResolvedAdminPluginExtensions,
+	type ResolvedAdminExtensions,
 	type ResolvedAdminPluginPairs,
 } from "./plugin";
+
+export { resolvePluginFields, type ResolvedPluginField } from "./plugin-registry";

package/src/local-row-label.ts

@@ -0,0 +1,87 @@
+import type { Component } from "svelte";
+import type { SchemaField } from "@riducms/protocol";
+import type { RowLabelComponentProps } from "./row-label";
+import { decodeComponentConfig } from "./component-config";
+
+/** Props for an application-local array/block heading; row data is read-only and config is decoded. */
+export type RowLabelProps<Config = undefined> = Omit<RowLabelComponentProps, "config"> &
+	([Config] extends [undefined] ? { config?: never } : { config: Config });
+/** Heading component plus a synchronous settings decoder, required when Config is not undefined. */
+export type RowLabelDefinition<Config = undefined> = {
+	component: Component<RowLabelProps<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-row-label");
+const registered = new WeakSet<RegisteredRowLabel>();
+/** Helper result stored in `defineAdmin({ rowLabels: ... })`; do not construct it manually. */
+export interface RegisteredRowLabel {
+	readonly [registration]: true;
+	readonly component: Component<never>;
+	decode(field: SchemaField): unknown;
+}
+
+/**
+ * Register a custom heading for an array or block row in your application.
+ *
+ * Put the result under an `app:name` key in `defineAdmin`'s `rowLabels`. Select
+ * that key in Go with `field.Admin{RowLabel: field.Component("app:name")}`.
+ * Keep `RowLabelPath` for the plain-text name used by row actions and screen readers.
+ *
+ * `component` is required and receives `RowLabelProps`: `row` contains current,
+ * unsaved values, and `rowNumber` starts at one. Display a summary here; use a
+ * field component for controls that edit values.
+ *
+ * Add `decodeConfig` when the Go `field.Component` call supplies settings. Return
+ * checked settings synchronously, or throw a useful error. A decoder requires a
+ * Go configuration object, even for empty settings; without one, omit Go settings.
+ *
+ * @param definition The heading component and optional settings decoder.
+ * @returns A frozen registration for `defineAdmin`'s `rowLabels` map. It does not
+ * choose a Go field or mount the component until the admin renders that field.
+ * @throws If the component is invalid. `ridu check` also checks Go selections and settings.
+ * @example
+ * ```ts
+ * import { defineAdmin, defineRowLabel } from '@riducms/plugin/admin';
+ * import { generatedAdminPlugins } from './ridu.plugins.generated';
+ * import LinkRowLabel from './components/link-row-label.svelte';
+ *
+ * export default defineAdmin({
+ *   plugins: generatedAdminPlugins,
+ *   rowLabels: {
+ *     'app:linkSummary': defineRowLabel({ component: LinkRowLabel })
+ *   }
+ * });
+ * ```
+ */
+export function defineRowLabel<Config = undefined>(
+	definition: RowLabelDefinition<Config>
+): RegisteredRowLabel {
+	if (typeof definition.component !== "function")
+		throw new Error("A row label requires a Svelte component.");
+	const { component, decodeConfig } = definition;
+	const label = Object.freeze({
+		[registration]: true as const,
+		component,
+		decode(field: SchemaField): unknown {
+			const selection = field.nested?.rowLabelComponent;
+			try {
+				return decodeComponentConfig(selection, decodeConfig);
+			} catch (error) {
+				throw new Error(
+					`Row label ${selection?.reference} config for ${field.path} is invalid: ${error instanceof Error ? error.message : String(error)}`
+				);
+			}
+		},
+	});
+	registered.add(label);
+	return label;
+}
+
+export function isRegisteredRowLabel(value: RegisteredRowLabel): boolean {
+	return registered.has(value);
+}

package/src/plugin-registry.ts

@@ -0,0 +1,188 @@
+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";
+
+/** A registered field editor with the names Ridu uses to select it. Returned by registry resolution. */
+export interface ResolvedPluginField {
+	/** Owning Go/admin plugin key. */
+	readonly owner: string;
+	/** Field-type key for a default editor, or component name for an explicitly selected editor. */
+	readonly key: string;
+	/** Present only for editors registered in `components` and selected by Go `AdminComponent`. */
+	readonly componentKey?: string;
+	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.
+ * Used by Ridu's runtime/check tooling; authors normally call the registration
+ * helpers and retain their generated plugin list instead of invoking this directly.
+ */
+export function resolvePluginFields(
+	plugins: readonly AdminPlugin[]
+): readonly ResolvedPluginField[] {
+	const owners = new Set<string>();
+	const identities = new Set<string>();
+	const resolved: ResolvedPluginField[] = [];
+	for (const plugin of plugins) {
+		if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(plugin.key) || owners.has(plugin.key))
+			throw new Error(`Invalid or duplicate admin plugin key ${plugin.key}.`);
+		if (plugin.apiVersion !== ADMIN_PLUGIN_API_VERSION)
+			throw new Error(
+				`Admin plugin ${plugin.key} uses API ${plugin.apiVersion}; this admin supports ${ADMIN_PLUGIN_API_VERSION}.`
+			);
+		if (!Number.isSafeInteger(plugin.pairingVersion) || plugin.pairingVersion < 1)
+			throw new Error(`Admin plugin ${plugin.key} requires a positive pairingVersion.`);
+		owners.add(plugin.key);
+		for (const [kind, entries] of [
+			["fields", plugin.fields],
+			["components", plugin.components],
+		] as const) {
+			if (entries === undefined) continue;
+			if (
+				typeof entries !== "object" ||
+				entries === null ||
+				Array.isArray(entries) ||
+				(Object.getPrototypeOf(entries) !== Object.prototype &&
+					Object.getPrototypeOf(entries) !== null)
+			)
+				throw new Error(`Plugin ${plugin.key} ${kind} must be a keyed registration object.`);
+			for (const [key, registration] of Object.entries(entries)) {
+				if (
+					!(
+						kind === "fields" ? /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/ : /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
+					).test(key)
+				)
+					throw new Error(`Invalid plugin ${kind} key ${key}.`);
+				assertPluginFieldRegistration(registration);
+				if (
+					kind === "fields"
+						? registration.type !== "plugin" || registration.fieldType !== undefined
+						: registration.type === "plugin" && registration.fieldType === undefined
+				)
+					throw new Error(`Plugin ${plugin.key} ${kind}.${key} uses the wrong registration kind.`);
+				const identity = kind === "fields" ? `field:${key}` : `component:${plugin.key}:${key}`;
+				if (identities.has(identity))
+					throw new Error(`Duplicate admin field renderer ${identity}.`);
+				identities.add(identity);
+				resolved.push(
+					Object.freeze({
+						owner: plugin.key,
+						key,
+						registration,
+						...(kind === "components" ? { componentKey: key } : {}),
+					})
+				);
+			}
+		}
+	}
+	return Object.freeze(resolved);
+}
+
+/** Canonical manifest, actual executable registrations, and the same decoders as the host. */
+export function validatePluginManifest(
+	plugins: readonly AdminPlugin[],
+	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)
+		for (const item of registrations) {
+			if (
+				item.registration.fieldType !== undefined &&
+				!manifest.plugins.some((plugin) =>
+					plugin.fieldTypes?.some((field) => field.key === item.registration.fieldType)
+				)
+			)
+				throw new Error(
+					`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(", ")}).`
+				);
+		}
+		if (complete)
+			for (const plugin of plugins) {
+				if (
+					!manifest.plugins.some(
+						(backend) => backend.key === plugin.key && backend.admin !== undefined
+					)
+				)
+					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)}`
+				);
+			}
+			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);
+		}
+	};
+	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"));
+}