@bpmnkit/plugins 0.0.8

package/dist/config-panel-bpmn/template-engine.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a Camunda element template into the PanelSchema + PanelAdapter pair
+ * used by the config-panel plugin renderer.
+ */
+import type { PanelAdapter, PanelSchema } from "../config-panel/index.js";
+import type { ElementTemplate } from "./template-types.js";
+export interface TemplateRegistration {
+    schema: PanelSchema;
+    adapter: PanelAdapter;
+}
+/**
+ * Builds a PanelSchema + PanelAdapter pair from an element template descriptor.
+ * The result is cached by the caller (per template id) so reference-equality
+ * comparisons in the renderer work correctly.
+ */
+export declare function buildRegistrationFromTemplate(template: ElementTemplate): TemplateRegistration;
+//# sourceMappingURL=template-engine.d.ts.map

package/dist/config-panel-bpmn/template-engine.js

@@ -0,0 +1,307 @@
+import { zeebeExtensionsToXmlElements } from "@bpmnkit/core";
+import { findFlowElement, getAdHocAttr, getIoInput, getTaskHeader, parseZeebeExtensions, updateFlowElement, xmlLocalName, } from "./util.js";
+// ── Condition conversion ──────────────────────────────────────────────────────
+function buildConditionFn(cond) {
+    if ("allMatch" in cond) {
+        const fns = cond.allMatch.map((c) => buildConditionFn(c));
+        return (values) => fns.every((fn) => fn(values));
+    }
+    if ("equals" in cond) {
+        return (values) => values[cond.property] === cond.equals;
+    }
+    if ("oneOf" in cond) {
+        const set = new Set(cond.oneOf);
+        return (values) => set.has(values[cond.property]);
+    }
+    if ("isActive" in cond) {
+        const expected = cond.isActive;
+        return (values) => Boolean(values[cond.property]) === expected;
+    }
+    return () => true;
+}
+// ── Property key derivation ───────────────────────────────────────────────────
+/**
+ * Derive the panel field key for a template property.
+ *
+ * The key is used as:
+ * - The field key in PanelSchema (for rendering + condition references)
+ * - The value-map key in the adapter (for read/write)
+ *
+ * Priority: property.id > binding-derived name
+ */
+function getPropertyKey(prop) {
+    if (prop.id)
+        return prop.id;
+    const b = prop.binding;
+    if (b.type === "zeebe:input")
+        return b.name;
+    if (b.type === "zeebe:output")
+        return b.source;
+    if (b.type === "zeebe:taskHeader")
+        return b.key;
+    if (b.type === "zeebe:taskDefinition")
+        return `taskDef.${b.property}`;
+    if (b.type === "zeebe:taskDefinition:type")
+        return "taskDef.type";
+    if (b.type === "property")
+        return b.name;
+    if (b.type === "zeebe:property")
+        return b.name;
+    if (b.type === "zeebe:adHoc")
+        return `adHoc.${b.property}`;
+    return "";
+}
+// ── Property → FieldSchema ────────────────────────────────────────────────────
+function propToFieldSchema(prop) {
+    const key = getPropertyKey(prop);
+    const condition = prop.condition ? buildConditionFn(prop.condition) : undefined;
+    const base = {
+        key,
+        label: prop.label ?? key,
+        type: "text",
+        placeholder: prop.placeholder,
+        hint: prop.description,
+        tooltip: prop.tooltip,
+        condition,
+        ...(prop.constraints?.notEmpty === true ? { required: true } : {}),
+    };
+    // FEEL mode: "optional" → toggle, "required" → fixed (always FEEL, no toggle)
+    const feelOptional = prop.feel === "optional";
+    const feelRequired = prop.feel === "required";
+    const hasFeel = feelOptional || feelRequired;
+    switch (prop.type) {
+        case "Text":
+            if (hasFeel) {
+                return { ...base, type: "feel-expression", ...(feelRequired ? { feelFixed: true } : {}) };
+            }
+            return { ...base, type: "textarea" };
+        case "Dropdown":
+            return {
+                ...base,
+                type: "select",
+                options: (prop.choices ?? []).map((c) => ({ value: c.value, label: c.name })),
+            };
+        case "Boolean":
+            return { ...base, type: "toggle" };
+        case "Number":
+            return {
+                ...base,
+                type: "text",
+                placeholder: prop.placeholder ?? String(prop.value ?? ""),
+            };
+        default:
+            // String
+            if (hasFeel) {
+                return { ...base, type: "feel-expression", ...(feelRequired ? { feelFixed: true } : {}) };
+            }
+            return base;
+    }
+}
+// ── Adapter read/write helpers ────────────────────────────────────────────────
+function readPropertyValue(ext, el, prop) {
+    const b = prop.binding;
+    if (b.type === "zeebe:input")
+        return getIoInput(ext, b.name);
+    if (b.type === "zeebe:taskHeader")
+        return getTaskHeader(ext, b.key);
+    if (b.type === "zeebe:taskDefinition" && b.property === "type")
+        return ext.taskDefinition?.type;
+    if (b.type === "zeebe:taskDefinition" && b.property === "retries")
+        return ext.taskDefinition?.retries;
+    if (b.type === "zeebe:taskDefinition:type")
+        return ext.taskDefinition?.type;
+    if (b.type === "property" && b.name === "name")
+        return el.name;
+    if (b.type === "zeebe:adHoc")
+        return getAdHocAttr(el.extensionElements, b.property);
+    return undefined;
+}
+function applyBinding(binding, value, inputs, headers, taskDef, adHocProps) {
+    if (binding.type === "zeebe:input") {
+        inputs.push({ source: value, target: binding.name });
+    }
+    else if (binding.type === "zeebe:taskHeader") {
+        headers.push({ key: binding.key, value });
+    }
+    else if (binding.type === "zeebe:taskDefinition" && binding.property === "type") {
+        taskDef.type = value;
+    }
+    else if (binding.type === "zeebe:taskDefinition" && binding.property === "retries") {
+        taskDef.retries = value;
+    }
+    else if (binding.type === "zeebe:taskDefinition:type") {
+        taskDef.type = value;
+    }
+    else if (binding.type === "zeebe:adHoc") {
+        if (binding.property === "outputCollection")
+            adHocProps.outputCollection = value;
+        else if (binding.property === "outputElement")
+            adHocProps.outputElement = value;
+        else if (binding.property === "activeElementsCollection")
+            adHocProps.activeElementsCollection = value;
+    }
+}
+/**
+ * Builds a PanelSchema + PanelAdapter pair from an element template descriptor.
+ * The result is cached by the caller (per template id) so reference-equality
+ * comparisons in the renderer work correctly.
+ */
+export function buildRegistrationFromTemplate(template) {
+    // Collect visible (non-hidden) properties and their keys
+    const visibleProps = template.properties.filter((p) => p.type !== "Hidden");
+    const propsByKey = new Map();
+    for (const prop of visibleProps) {
+        const key = getPropertyKey(prop);
+        if (key)
+            propsByKey.set(key, prop);
+    }
+    // Collect hidden properties (written at save time with their fixed default values)
+    const hiddenProps = template.properties.filter((p) => p.type === "Hidden");
+    // Group visible properties by their group id
+    const byGroup = new Map();
+    const ungrouped = [];
+    for (const prop of visibleProps) {
+        if (prop.group) {
+            const arr = byGroup.get(prop.group);
+            if (arr)
+                arr.push(prop);
+            else
+                byGroup.set(prop.group, [prop]);
+        }
+        else {
+            ungrouped.push(prop);
+        }
+    }
+    // Build schema groups
+    // "General" group always comes first: name + any ungrouped properties
+    const nameField = {
+        key: "name",
+        label: "Name",
+        type: "text",
+        placeholder: "Task name",
+    };
+    /**
+     * Action button that strips the zeebe:modelerTemplate stamp so the renderer
+     * falls back to the generic connector selector on the next diagram:change.
+     * The sentinel value "__change_connector" is intercepted by write() below.
+     */
+    const changeConnectorField = {
+        key: "__change_connector",
+        label: "Change connector",
+        type: "action",
+        hint: "Switch to a different connector or custom task type.",
+        onClick: (_values, setValue) => {
+            setValue("__change_connector", "remove");
+        },
+    };
+    const generalFields = [
+        nameField,
+        changeConnectorField,
+        ...ungrouped.map((p) => propToFieldSchema(p)),
+    ];
+    const schemaGroups = [{ id: "general", label: "General", fields: generalFields }];
+    for (const tg of template.groups ?? []) {
+        const props = byGroup.get(tg.id);
+        if (!props || props.length === 0)
+            continue;
+        schemaGroups.push({
+            id: tg.id,
+            label: tg.label,
+            fields: props.map((p) => propToFieldSchema(p)),
+        });
+    }
+    const schema = {
+        compact: [nameField],
+        groups: schemaGroups,
+        ...(template.documentationRef ? { docsUrl: template.documentationRef } : {}),
+        templateName: template.name,
+    };
+    // Build adapter
+    const adapter = {
+        read(defs, id) {
+            const el = findFlowElement(defs, id);
+            if (!el)
+                return {};
+            const ext = parseZeebeExtensions(el.extensionElements);
+            const values = { name: el.name ?? "" };
+            for (const [key, prop] of propsByKey) {
+                const raw = readPropertyValue(ext, el, prop);
+                // Fall back to template default when not yet written to XML
+                values[key] = raw ?? String(prop.value ?? "");
+            }
+            return values;
+        },
+        write(defs, id, values) {
+            // "Change connector" button — strip the template stamp so the renderer
+            // falls back to the generic connector selector on the next render.
+            if (values.__change_connector === "remove") {
+                return updateFlowElement(defs, id, (el) => {
+                    const { "zeebe:modelerTemplate": _tm, "zeebe:modelerTemplateVersion": _tmv, "zeebe:modelerTemplateIcon": _tmi, ...rest } = el.unknownAttributes;
+                    return { ...el, unknownAttributes: rest };
+                });
+            }
+            return updateFlowElement(defs, id, (el) => {
+                const name = typeof values.name === "string" ? values.name || undefined : el.name;
+                const inputs = [];
+                const headers = [];
+                const taskDef = {};
+                const adHocProps = {};
+                // 1. Apply hidden properties first (fixed default values)
+                for (const prop of hiddenProps) {
+                    const val = String(prop.value ?? "");
+                    if (val)
+                        applyBinding(prop.binding, val, inputs, headers, taskDef, adHocProps);
+                }
+                // 2. Apply user-entered values for visible properties
+                for (const [key, prop] of propsByKey) {
+                    const raw = values[key];
+                    const val = typeof raw === "boolean" ? String(raw) : typeof raw === "string" ? raw : "";
+                    const isBlank = val === "" || val === undefined;
+                    // Skip optional blank values — don't write to XML
+                    if (isBlank && prop.optional)
+                        continue;
+                    // Skip truly blank fields with no default
+                    if (isBlank && prop.value === undefined)
+                        continue;
+                    const effectiveVal = val !== "" ? val : String(prop.value ?? "");
+                    if (!effectiveVal)
+                        continue;
+                    applyBinding(prop.binding, effectiveVal, inputs, headers, taskDef, adHocProps);
+                }
+                // Preserve non-Zeebe extension elements
+                const ZEEBE_LOCAL = new Set(["taskDefinition", "ioMapping", "taskHeaders", "adHoc"]);
+                const otherExts = el.extensionElements.filter((x) => !ZEEBE_LOCAL.has(xmlLocalName(x.name)));
+                const newZeebeExts = zeebeExtensionsToXmlElements({
+                    taskDefinition: taskDef.type
+                        ? { type: taskDef.type, retries: taskDef.retries || undefined }
+                        : undefined,
+                    ioMapping: inputs.length > 0 ? { inputs, outputs: [] } : undefined,
+                    taskHeaders: headers.length > 0 ? { headers } : undefined,
+                    adHoc: (adHocProps.outputCollection ??
+                        adHocProps.outputElement ??
+                        adHocProps.activeElementsCollection)
+                        ? adHocProps
+                        : undefined,
+                });
+                return {
+                    ...el,
+                    name,
+                    extensionElements: [...otherExts, ...newZeebeExts],
+                    // Stamp the modelerTemplate attribute so the editor recognizes it
+                    unknownAttributes: {
+                        ...el.unknownAttributes,
+                        "zeebe:modelerTemplate": template.id,
+                        ...(template.version !== undefined
+                            ? { "zeebe:modelerTemplateVersion": String(template.version) }
+                            : {}),
+                        ...(template.icon?.contents
+                            ? { "zeebe:modelerTemplateIcon": template.icon.contents }
+                            : {}),
+                    },
+                };
+            });
+        },
+    };
+    return { schema, adapter };
+}
+//# sourceMappingURL=template-engine.js.map

package/dist/config-panel-bpmn/template-to-service-task.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Convert an element template + user-provided values into ServiceTaskOptions
+ * for use with the core `Bpmn` builder.
+ */
+import type { ServiceTaskOptions } from "@bpmnkit/core";
+import type { ElementTemplate } from "./template-types.js";
+/**
+ * Convert a Camunda element template into `ServiceTaskOptions` for the core
+ * `Bpmn` builder, applying `values` for user-configurable properties and
+ * fixed template defaults for Hidden properties.
+ *
+ * @example
+ * ```typescript
+ * import { Bpmn } from "@bpmnkit/core";
+ * import { CAMUNDA_CONNECTOR_TEMPLATES, templateToServiceTaskOptions } from "@bpmnkit/canvas-plugin-config-panel-bpmn";
+ *
+ * const kafka = CAMUNDA_CONNECTOR_TEMPLATES.find(t => t.id === "io.camunda.connectors.KAFKA.v1")!;
+ * const defs = Bpmn.createProcess("proc")
+ *   .startEvent("start")
+ *   .serviceTask("publish", templateToServiceTaskOptions(kafka, {
+ *     "topic.bootstrapServers": "localhost:9092",
+ *     "topic.topicName": "orders",
+ *     "message.value": "= order",
+ *   }))
+ *   .endEvent("end")
+ *   .build();
+ * ```
+ */
+export declare function templateToServiceTaskOptions(template: ElementTemplate, values?: Record<string, string>): ServiceTaskOptions;
+//# sourceMappingURL=template-to-service-task.d.ts.map

package/dist/config-panel-bpmn/template-to-service-task.js

@@ -0,0 +1,92 @@
+/** Derive the lookup key for a template property (same logic as the template engine). */
+function propertyKey(prop) {
+    if (prop.id)
+        return prop.id;
+    const b = prop.binding;
+    if (b.type === "zeebe:input")
+        return b.name;
+    if (b.type === "zeebe:output")
+        return b.source;
+    if (b.type === "zeebe:taskHeader")
+        return b.key;
+    if (b.type === "zeebe:taskDefinition")
+        return `taskDef.${b.property}`;
+    if (b.type === "zeebe:taskDefinition:type")
+        return "taskDef.type";
+    if (b.type === "property")
+        return b.name;
+    if (b.type === "zeebe:property")
+        return b.name;
+    return "";
+}
+function applyBinding(binding, value, inputs, taskHeaders, out) {
+    if (binding.type === "zeebe:input") {
+        inputs.push({ source: value, target: binding.name });
+    }
+    else if (binding.type === "zeebe:taskHeader") {
+        taskHeaders[binding.key] = value;
+    }
+    else if (binding.type === "zeebe:taskDefinition" && binding.property === "type") {
+        out.taskType = value;
+    }
+    else if (binding.type === "zeebe:taskDefinition" && binding.property === "retries") {
+        out.retries = value;
+    }
+    else if (binding.type === "zeebe:taskDefinition:type") {
+        out.taskType = value;
+    }
+}
+/**
+ * Convert a Camunda element template into `ServiceTaskOptions` for the core
+ * `Bpmn` builder, applying `values` for user-configurable properties and
+ * fixed template defaults for Hidden properties.
+ *
+ * @example
+ * ```typescript
+ * import { Bpmn } from "@bpmnkit/core";
+ * import { CAMUNDA_CONNECTOR_TEMPLATES, templateToServiceTaskOptions } from "@bpmnkit/canvas-plugin-config-panel-bpmn";
+ *
+ * const kafka = CAMUNDA_CONNECTOR_TEMPLATES.find(t => t.id === "io.camunda.connectors.KAFKA.v1")!;
+ * const defs = Bpmn.createProcess("proc")
+ *   .startEvent("start")
+ *   .serviceTask("publish", templateToServiceTaskOptions(kafka, {
+ *     "topic.bootstrapServers": "localhost:9092",
+ *     "topic.topicName": "orders",
+ *     "message.value": "= order",
+ *   }))
+ *   .endEvent("end")
+ *   .build();
+ * ```
+ */
+export function templateToServiceTaskOptions(template, values = {}) {
+    const inputs = [];
+    const taskHeaders = {};
+    const out = {
+        taskType: "",
+        retries: undefined,
+    };
+    for (const prop of template.properties) {
+        if (prop.type === "Hidden") {
+            if (typeof prop.value === "string" && prop.value) {
+                applyBinding(prop.binding, prop.value, inputs, taskHeaders, out);
+            }
+            continue;
+        }
+        const key = propertyKey(prop);
+        const val = values[key] ?? (typeof prop.value === "string" ? prop.value : undefined);
+        if (!val)
+            continue;
+        applyBinding(prop.binding, val, inputs, taskHeaders, out);
+    }
+    return {
+        name: values.name ?? template.name,
+        taskType: out.taskType,
+        retries: out.retries,
+        modelerTemplate: template.id,
+        modelerTemplateVersion: template.version !== undefined ? String(template.version) : undefined,
+        modelerTemplateIcon: template.icon?.contents,
+        ioMapping: inputs.length > 0 ? { inputs } : undefined,
+        taskHeaders: Object.keys(taskHeaders).length > 0 ? taskHeaders : undefined,
+    };
+}
+//# sourceMappingURL=template-to-service-task.js.map

package/dist/config-panel-bpmn/template-types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * TypeScript types matching the Camunda element template JSON schema.
+ * https://github.com/camunda/element-templates-json-schema
+ */
+export interface ElementTemplate {
+    /** Unique template identifier (reverse-domain, e.g. "io.camunda.connectors.HttpJson.v2"). */
+    id: string;
+    /** Display name shown in the template catalog. */
+    name: string;
+    /** Short description. */
+    description?: string;
+    /** Integer version; templates with the same id + different version are distinct. */
+    version?: number;
+    /** BPMN element types this template applies to (e.g. "bpmn:ServiceTask", "bpmn:Task"). */
+    appliesTo: string[];
+    /** Forces the element to be converted to this type on apply. */
+    elementType?: {
+        value: string;
+    };
+    /** UI section definitions (collapsible groups). */
+    groups?: TemplateGroup[];
+    /** All property definitions. */
+    properties: TemplateProperty[];
+    /** Link to external documentation. */
+    documentationRef?: string;
+    /** Custom icon: { contents: "data:image/svg+xml;base64,..." } */
+    icon?: {
+        contents: string;
+    };
+}
+export interface TemplateGroup {
+    id: string;
+    label: string;
+    tooltip?: string;
+    openByDefault?: boolean;
+}
+export interface TemplateProperty {
+    /** Unique key used in condition references. Falls back to binding name if absent. */
+    id?: string;
+    /** Label shown above the input. Hidden properties have no label. */
+    label?: string;
+    /** Hint text shown below the input. */
+    description?: string;
+    /** UI control type. */
+    type: "String" | "Text" | "Hidden" | "Dropdown" | "Boolean" | "Number";
+    /** Default value applied when the template is first used. */
+    value?: string | number | boolean;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** If true, empty values are not written to the BPMN XML. */
+    optional?: boolean;
+    /** FEEL expression mode (only relevant for String/Text). */
+    feel?: "optional" | "required" | "static";
+    /** Which template group this property belongs to. */
+    group?: string;
+    /** Tooltip text. */
+    tooltip?: string;
+    /** How this property maps to the BPMN XML. */
+    binding: TemplateBinding;
+    /** Conditional visibility. */
+    condition?: TemplateCondition;
+    /** Required for Dropdown type. */
+    choices?: Array<{
+        name: string;
+        value: string;
+    }>;
+    /** Validation constraints. */
+    constraints?: {
+        notEmpty?: boolean;
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string | {
+            value: string;
+            message: string;
+        };
+    };
+}
+/** All supported binding types. */
+export type TemplateBinding = {
+    type: "property";
+    name: string;
+}
+/** @deprecated Use zeebe:taskDefinition with property field instead. */
+ | {
+    type: "zeebe:taskDefinition:type";
+} | {
+    type: "zeebe:taskDefinition";
+    property: "type" | "retries";
+} | {
+    type: "zeebe:input";
+    name: string;
+} | {
+    type: "zeebe:output";
+    source: string;
+} | {
+    type: "zeebe:taskHeader";
+    key: string;
+} | {
+    type: "zeebe:property";
+    name: string;
+} | {
+    type: "zeebe:adHoc";
+    property: "outputCollection" | "outputElement" | "activeElementsCollection";
+};
+/** Condition controlling whether a property is shown in the UI. */
+export type TemplateCondition = {
+    property: string;
+    equals: string;
+    type?: string;
+} | {
+    property: string;
+    oneOf: string[];
+    type?: string;
+} | {
+    property: string;
+    isActive: boolean;
+    type?: string;
+} | {
+    allMatch: Array<{
+        property: string;
+        equals?: string;
+        oneOf?: string[];
+        isActive?: boolean;
+    }>;
+};
+//# sourceMappingURL=template-types.d.ts.map

package/dist/config-panel-bpmn/template-types.js

@@ -0,0 +1,6 @@
+/**
+ * TypeScript types matching the Camunda element template JSON schema.
+ * https://github.com/camunda/element-templates-json-schema
+ */
+export {};
+//# sourceMappingURL=template-types.js.map

package/dist/config-panel-bpmn/templates/generated.d.ts

@@ -0,0 +1,3 @@
+import type { ElementTemplate } from "../template-types.js";
+export declare const CAMUNDA_CONNECTOR_TEMPLATES: ElementTemplate[];
+//# sourceMappingURL=generated.d.ts.map