@n8n/frontend-module-sdk 0.8.1 → 0.9.0

package/package.json

@@ -1,27 +1,29 @@
 {
   "type": "module",
   "name": "@n8n/frontend-module-sdk",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "main": "src/index.ts",
   "import": "src/index.ts",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
+    "@n8n/api-types": "1.39.0",
+    "@n8n/design-system": "2.38.0",
+    "@n8n/utils": "1.47.0",
+    "n8n-workflow": "2.39.0",
     "vue": "^3.5.13",
-    "vue-router": "^4.5.0",
-    "@n8n/api-types": "1.38.1",
-    "@n8n/design-system": "2.37.1"
+    "vue-router": "^4.5.0"
   },
   "devDependencies": {
+    "@n8n/eslint-config": "0.0.1",
+    "@n8n/typescript-config": "1.11.0",
+    "@n8n/vitest-config": "1.21.0",
     "typescript": "6.0.2",
     "unplugin-icons": "^23.0.1",
     "vite": "^8.0.2",
     "vitest": "^4.1.9",
-    "vue-tsc": "^2.2.8",
-    "@n8n/eslint-config": "0.0.1",
-    "@n8n/typescript-config": "1.11.0",
-    "@n8n/vitest-config": "1.21.0"
+    "vue-tsc": "^2.2.8"
   },
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://n8n.io",

package/src/index.ts

@@ -6,3 +6,4 @@ export * as modalRegistry from './registries/modalRegistry';
 export * from './registries/resourceRegistry';
 export * as pushHandlerRegistry from './registries/pushHandlerRegistry';
 export * as commandRegistry from './registries/commandRegistry';
+export * as parameterInputRegistry from './registries/parameterInputRegistry';

package/src/registries/parameterInputRegistry.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { computed } from 'vue';
+import type { Component } from 'vue';
+
+import * as parameterInputRegistry from './parameterInputRegistry';
+import type { ParameterInputContribution, ParameterInputType } from '../types/parameterInput';
+
+describe('parameterInputRegistry', () => {
+	const resourceLocatorComponent = { name: 'TestResourceLocator' } as Component;
+	const workflowSelectorComponent = { name: 'TestWorkflowSelector' } as Component;
+	const asyncComponent = async (): Promise<Component> =>
+		await Promise.resolve({ name: 'AsyncTestInput' } as Component);
+
+	const resourceLocator: ParameterInputContribution = {
+		type: 'resourceLocator',
+		component: resourceLocatorComponent,
+		capabilities: { ownsExpressionRendering: true, ownsFromAiOverride: true, disableDrop: true },
+	};
+
+	const workflowSelector: ParameterInputContribution = {
+		type: 'workflowSelector',
+		component: workflowSelectorComponent,
+	};
+
+	const lazyInput: ParameterInputContribution = {
+		type: 'filter',
+		component: asyncComponent,
+	};
+
+	beforeEach(() => {
+		parameterInputRegistry.clear();
+	});
+
+	describe('register', () => {
+		it('should register a contribution under its parameter type', () => {
+			parameterInputRegistry.register(resourceLocator);
+
+			expect(parameterInputRegistry.has('resourceLocator')).toBe(true);
+			expect(parameterInputRegistry.get('resourceLocator')).toEqual(resourceLocator);
+		});
+
+		it('should register multiple contributions', () => {
+			parameterInputRegistry.register(resourceLocator);
+			parameterInputRegistry.register(workflowSelector);
+
+			expect(parameterInputRegistry.getAll().size).toBe(2);
+		});
+
+		it('should accept a lazy component factory', () => {
+			parameterInputRegistry.register(lazyInput);
+
+			expect(parameterInputRegistry.get('filter')?.component).toBe(asyncComponent);
+		});
+
+		it('should warn and skip when a different contribution claims a taken type', () => {
+			const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+			parameterInputRegistry.register(resourceLocator);
+			parameterInputRegistry.register({
+				type: 'resourceLocator',
+				component: workflowSelectorComponent,
+			});
+
+			expect(consoleSpy).toHaveBeenCalledWith(
+				'Parameter input for type "resourceLocator" is already registered. Skipping.',
+			);
+			expect(parameterInputRegistry.get('resourceLocator')?.component).toBe(
+				resourceLocatorComponent,
+			);
+
+			consoleSpy.mockRestore();
+		});
+
+		it('should treat a replay of the same contribution as a no-op', () => {
+			const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+			parameterInputRegistry.register(resourceLocator);
+			parameterInputRegistry.register(resourceLocator);
+
+			expect(consoleSpy).not.toHaveBeenCalled();
+			expect(parameterInputRegistry.getAll().size).toBe(1);
+
+			consoleSpy.mockRestore();
+		});
+	});
+
+	describe('get', () => {
+		it('should return undefined for an unregistered type', () => {
+			parameterInputRegistry.register(resourceLocator);
+
+			expect(parameterInputRegistry.get('string')).toBeUndefined();
+			expect(parameterInputRegistry.has('string')).toBe(false);
+		});
+
+		it('should return undefined once every contribution is cleared', () => {
+			parameterInputRegistry.register(resourceLocator);
+			parameterInputRegistry.clear();
+
+			expect(parameterInputRegistry.get('resourceLocator')).toBeUndefined();
+		});
+	});
+
+	describe('unregister', () => {
+		it('should remove a registered type', () => {
+			parameterInputRegistry.register(resourceLocator);
+			parameterInputRegistry.unregister('resourceLocator');
+
+			expect(parameterInputRegistry.has('resourceLocator')).toBe(false);
+		});
+
+		it('should let the type be claimed again after removal', () => {
+			parameterInputRegistry.register(resourceLocator);
+			parameterInputRegistry.unregister('resourceLocator');
+			parameterInputRegistry.register({
+				type: 'resourceLocator',
+				component: workflowSelectorComponent,
+			});
+
+			expect(parameterInputRegistry.get('resourceLocator')?.component).toBe(
+				workflowSelectorComponent,
+			);
+		});
+	});
+
+	describe('getAll', () => {
+		it('should return a copy, so a caller cannot mutate the registry', () => {
+			parameterInputRegistry.register(resourceLocator);
+
+			parameterInputRegistry.getAll().delete('resourceLocator');
+
+			expect(parameterInputRegistry.has('resourceLocator')).toBe(true);
+		});
+	});
+
+	describe('reactivity', () => {
+		it('should re-evaluate a computed when a contribution is registered', () => {
+			const resolved = computed(() => parameterInputRegistry.get('resourceLocator'));
+
+			expect(resolved.value).toBeUndefined();
+
+			parameterInputRegistry.register(resourceLocator);
+
+			expect(resolved.value).toEqual(resourceLocator);
+		});
+
+		it('should not wrap the component in a reactive proxy', () => {
+			parameterInputRegistry.register(resourceLocator);
+
+			// Shallow registry: a reactive component logs "Vue received a Component
+			// that was made a reactive object" and breaks `<component :is>`.
+			expect(parameterInputRegistry.get('resourceLocator')?.component).toBe(
+				resourceLocatorComponent,
+			);
+		});
+	});
+
+	describe('subscribe', () => {
+		it('should notify listeners on register and unregister', () => {
+			const listener =
+				vi.fn<(entries: Map<ParameterInputType, ParameterInputContribution>) => void>();
+			const unsubscribe = parameterInputRegistry.subscribe(listener);
+
+			parameterInputRegistry.register(resourceLocator);
+			expect(listener).toHaveBeenCalledTimes(1);
+			expect(listener.mock.calls[0]?.[0].get('resourceLocator')).toEqual(resourceLocator);
+
+			parameterInputRegistry.unregister('resourceLocator');
+			expect(listener).toHaveBeenCalledTimes(2);
+
+			unsubscribe();
+			parameterInputRegistry.register(workflowSelector);
+			expect(listener).toHaveBeenCalledTimes(2);
+		});
+
+		it('should not notify when unregistering a type that was never claimed', () => {
+			const listener = vi.fn();
+			const unsubscribe = parameterInputRegistry.subscribe(listener);
+
+			parameterInputRegistry.unregister('string');
+
+			expect(listener).not.toHaveBeenCalled();
+
+			unsubscribe();
+		});
+	});
+});

package/src/registries/parameterInputRegistry.ts

@@ -0,0 +1,72 @@
+import { shallowReactive } from 'vue';
+
+import type { ParameterInputContribution, ParameterInputType } from '../types/parameterInput';
+
+/**
+ * Shallow-reactive so the render path can derive from the registry with a plain
+ * `computed`. Shallow on purpose: a contribution's `component` must not be
+ * turned into a reactive object.
+ */
+const parameterInputs = shallowReactive(new Map<ParameterInputType, ParameterInputContribution>());
+const listeners = new Set<(entries: Map<ParameterInputType, ParameterInputContribution>) => void>();
+
+export function getAll(): Map<ParameterInputType, ParameterInputContribution> {
+	return new Map(parameterInputs);
+}
+
+function notifyListeners(): void {
+	listeners.forEach((listener) => listener(getAll()));
+}
+
+/**
+ * Claim `contribution.type` for this component. One owner per type: the shell's
+ * built-in branch for that type is what an unclaimed type falls back to.
+ */
+export function register(contribution: ParameterInputContribution): void {
+	const existing = parameterInputs.get(contribution.type);
+	if (existing) {
+		// Replaying the same contribution is how a re-login re-runs registration —
+		// a no-op, not a collision. Only a different contribution claiming a taken
+		// type is worth warning about.
+		if (existing !== contribution) {
+			console.warn(
+				`Parameter input for type "${contribution.type}" is already registered. Skipping.`,
+			);
+		}
+		return;
+	}
+
+	parameterInputs.set(contribution.type, contribution);
+	notifyListeners();
+}
+
+export function unregister(type: ParameterInputType): void {
+	if (parameterInputs.delete(type)) {
+		notifyListeners();
+	}
+}
+
+export function get(type: ParameterInputType): ParameterInputContribution | undefined {
+	return parameterInputs.get(type);
+}
+
+export function has(type: ParameterInputType): boolean {
+	return parameterInputs.has(type);
+}
+
+export function subscribe(
+	listener: (entries: Map<ParameterInputType, ParameterInputContribution>) => void,
+): () => void {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+
+/**
+ * Remove all registered parameter inputs. Primarily for test isolation.
+ */
+export function clear(): void {
+	parameterInputs.clear();
+	notifyListeners();
+}

package/src/types/descriptor.test.ts

@@ -43,4 +43,23 @@ describe('FrontendModuleDescription', () => {
 		expect(descriptor.commands?.[0]?.id).toBe('v2.open');
 		expect(descriptor.pushHandlers?.workflowActivated).toBeTypeOf('function');
 	});
+
+	it('accepts a parameter-input contribution with a lazy component', () => {
+		const descriptor: FrontendModuleDescription = {
+			id: 'inputs',
+			name: 'Inputs',
+			description: 'A descriptor contributing a parameter input',
+			icon: 'box',
+			parameterInputs: [
+				{
+					type: 'resourceLocator',
+					component: async () => await Promise.resolve({ name: 'ResourceLocator' }),
+					capabilities: { ownsExpressionRendering: true, disableDrop: true },
+				},
+			],
+		};
+
+		expect(descriptor.parameterInputs?.[0]?.type).toBe('resourceLocator');
+		expect(descriptor.parameterInputs?.[0]?.capabilities?.ownsFromAiOverride).toBeUndefined();
+	});
 });

package/src/types/descriptor.ts

@@ -5,6 +5,7 @@ import type { ModuleBanner } from './banner';
 import type { CommandBarEntry } from './command';
 import type { ModuleLocaleMessages } from './locale';
 import type { ModalDefinition } from './modal';
+import type { ParameterInputContribution } from './parameterInput';
 import type { ModulePushHandlers } from './push';
 import type { ResourceMetadata } from './resource';
 import type { ModuleSetupContext } from './setup';
@@ -48,6 +49,12 @@ export type FrontendModuleDescription = {
 	commands?: CommandBarEntry[];
 	/** Global keyboard shortcuts. */
 	shortcuts?: ModuleShortcut[];
+	/**
+	 * Custom parameter input components, resolved by `parameter.type` in the NDV
+	 * parameter render path. One owner per type; an unclaimed type keeps the
+	 * shell's built-in branch.
+	 */
+	parameterInputs?: ParameterInputContribution[];
 	/** Banners the module can contribute to the banner stack. */
 	banners?: ModuleBanner[];
 	/** Runs post-login, after the module is confirmed active. */

package/src/types/index.ts

@@ -1,5 +1,6 @@
 export type * from './descriptor';
 export type * from './modal';
+export type * from './parameterInput';
 export type * from './resource';
 export type * from './tabs';
 export type * from './push';

package/src/types/parameterInput.ts

@@ -0,0 +1,99 @@
+import type { EventBus } from '@n8n/utils/event-bus';
+import type {
+	INode,
+	INodeProperties,
+	NodeParameterValueType,
+	NodePropertyTypes,
+} from 'n8n-workflow';
+import type { Component } from 'vue';
+
+/**
+ * The `parameter.type` value a module claims. Deliberately the closed
+ * `NodePropertyTypes` union: a key the frontend accepts but a node author cannot
+ * declare would be a false surface. Widening the union later is additive.
+ */
+export type ParameterInputType = NodePropertyTypes;
+
+/**
+ * Props the shell passes to every contributed parameter input. The names and
+ * types match what `ParameterInput.vue` already passes to its built-in
+ * resource-locator branch, so an extracted component needs no adapter.
+ */
+export type ParameterInputProps = {
+	parameter: INodeProperties;
+	modelValue: NodeParameterValueType;
+	path: string;
+	node?: INode;
+	displayTitle: string;
+	isReadOnly: boolean;
+	isValueExpression: boolean;
+	expressionDisplayValue: string;
+	expressionComputedValue: unknown;
+	/** `undefined` until the async resolution of `loadOptionsDependsOn` settles. */
+	dependentParametersValues?: string | null;
+	/**
+	 * The parameter's validation issues, for an input that wants to place them
+	 * itself. The shell also draws `ParameterIssues` below the input for every
+	 * type outside the resource-locator family, so an input that renders these
+	 * shows them twice.
+	 */
+	parameterIssues: string[];
+	droppable: boolean;
+	eventBus?: EventBus;
+};
+
+/** Events the shell listens for on a contributed parameter input. */
+export type ParameterInputEmits = {
+	// Vue fixes the v-model event name; it cannot be camelCase.
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	'update:modelValue': [value: NodeParameterValueType];
+	modalOpenerClick: [];
+	focus: [];
+	blur: [];
+	drop: [value: string];
+};
+
+/**
+ * Capabilities the input takes over from `ParameterInputFull` / `ParameterInputWrapper`.
+ *
+ * These exist because `parameter.type` drives behaviour outside the render
+ * branch too — the expression toggle, the drop target and the from-AI override.
+ * An input that wins only the render branch would render correctly and still get
+ * the wrong capabilities. Every default keeps today's behaviour, so an input that
+ * needs none of it declares nothing.
+ */
+export type ParameterInputCapabilities = {
+	/**
+	 * The input draws its own expression editor, so the shell does not swap in
+	 * `ExpressionParameterInput` and does not show the expression selector for a
+	 * parameter whose modes are list-only.
+	 */
+	ownsExpressionRendering?: boolean;
+	/** The input owns the from-AI override, so the shell hides its own toggle. */
+	ownsFromAiOverride?: boolean;
+	/** The shell refuses drag-and-drop onto the field. */
+	disableDrop?: boolean;
+};
+
+/**
+ * A component the shell can drive with `ParameterInputProps`. Typing the
+ * contribution against it makes the prop contract a compiler check rather than
+ * a comment: a component declaring an incompatible prop is rejected at the
+ * registry boundary.
+ */
+export type ParameterInputComponent = Component<ParameterInputProps>;
+
+export type ParameterInputContribution = {
+	/** The `parameter.type` this entry renders. Also the registry key. */
+	type: ParameterInputType;
+	/**
+	 * Lazy on purpose: a `() => import()` keeps the module's `*.module.ts`
+	 * import-light (design §5.2) and keeps the component out of the shell chunk.
+	 *
+	 * A bare function here is read as the loader, following `ModalDefinition`. So a
+	 * functional component must be wrapped (`defineComponent(fn)`) or it is called
+	 * as a loader and never renders.
+	 */
+	component: ParameterInputComponent | (() => Promise<ParameterInputComponent>);
+	capabilities?: ParameterInputCapabilities;
+};