@bpmnkit/user-tasks 0.0.1

package/README.md

@@ -0,0 +1,160 @@
+<div align="center">
+  <a href="https://bpmnkit.com"><img src="https://bpmnkit.com/favicon.svg" width="72" height="72" alt="BPMN Kit logo"></a>
+  <h1>@bpmnkit/user-tasks</h1>
+  <p>Embeddable user task widget for Camunda 8 — form rendering, claim/complete actions, zero dependencies</p>
+
+  [![npm](https://img.shields.io/npm/v/@bpmnkit/user-tasks?style=flat-square&color=6244d7)](https://www.npmjs.com/package/@bpmnkit/user-tasks)
+  [![license](https://img.shields.io/npm/l/@bpmnkit/user-tasks?style=flat-square)](https://github.com/bpmnkit/monorepo/blob/main/LICENSE)
+  [![typescript](https://img.shields.io/badge/TypeScript-strict-6244d7?style=flat-square&logo=typescript&logoColor=white)](https://github.com/bpmnkit/monorepo)
+
+  [Website](https://bpmnkit.com) · [Documentation](https://docs.bpmnkit.com) · [GitHub](https://github.com/bpmnkit/monorepo) · [Changelog](https://github.com/bpmnkit/monorepo/blob/main/packages/user-tasks/CHANGELOG.md)
+</div>
+
+---
+
+## Overview
+
+`@bpmnkit/user-tasks` is a zero-dependency widget for rendering and interacting with Camunda 8 user tasks. Mount it into any HTML element to get a complete task UI — form rendering via `@bpmnkit/plugins/form-viewer`, claim/unclaim, complete, and optional reject actions.
+
+It connects to the `@bpmnkit/proxy` local server to fetch task forms and submit completions via the Camunda REST API.
+
+## Features
+
+- **Form rendering** — loads the task's linked Camunda Form and renders it via `@bpmnkit/plugins/form-viewer`
+- **Claim / Unclaim** — assigns or removes the task assignee
+- **Complete** — submits collected form variables to the Camunda API
+- **Reject** — optional reject/return action with a reason prompt
+- **Metadata display** — assignee, due date (with overdue highlight), and priority
+- **Theme support** — `light`, `dark`, or `neon` via `@bpmnkit/ui` design tokens
+- **Zero dependencies** — no framework required; mounts into any `HTMLElement`
+
+## Installation
+
+```sh
+npm install @bpmnkit/user-tasks @bpmnkit/proxy
+```
+
+## Quick Start
+
+```typescript
+import { createUserTaskWidget } from "@bpmnkit/user-tasks"
+
+const widget = createUserTaskWidget({
+  container: document.getElementById("task-panel")!,
+  task: {
+    userTaskKey: "2251799813685281",
+    name: "Review order",
+    assignee: "alice",
+    dueDate: "2025-06-01T12:00:00Z",
+    priority: 50,
+  },
+  proxyUrl: "http://localhost:3033",  // default
+  theme: "dark",
+  onComplete(variables) {
+    console.log("Task completed with", variables)
+  },
+  onClaim() {
+    console.log("Task claimed")
+  },
+  onUnclaim() {
+    console.log("Task unclaimed")
+  },
+  onReject(reason) {
+    console.log("Task rejected:", reason)
+  },
+})
+
+// Later: update the displayed task
+widget.setTask({ userTaskKey: "2251799813685999", name: "Approve invoice" })
+
+// Clean up
+widget.destroy()
+```
+
+## API Reference
+
+### `createUserTaskWidget(options)`
+
+```typescript
+interface UserTaskWidgetOptions {
+  /** The container element to render the widget into. */
+  container: HTMLElement
+  /** The user task to display. */
+  task: UserTask
+  /** Base URL of the proxy server. Default: "http://localhost:3033" */
+  proxyUrl?: string
+  /** Active profile name for x-profile header. */
+  profile?: string | null
+  /** Visual theme. Default: "neon" */
+  theme?: "light" | "dark" | "neon"
+  /** Called when the user completes the task. */
+  onComplete(variables: Record<string, unknown>): void
+  /** Called when the user claims the task. */
+  onClaim(): void
+  /** Called when the user unclaims the task. */
+  onUnclaim(): void
+  /** Called when the user rejects/returns the task. Optional — hides the Reject button if omitted. */
+  onReject?(reason: string): void
+}
+```
+
+Returns a `UserTaskWidgetApi`:
+
+```typescript
+interface UserTaskWidgetApi {
+  /** Update the displayed task and reload its form. */
+  setTask(task: UserTask): void
+  /** Remove the widget from the DOM and clean up. */
+  destroy(): void
+}
+```
+
+### `UserTask`
+
+```typescript
+interface UserTask {
+  userTaskKey: string
+  name?: string
+  assignee?: string
+  candidateGroups?: string[]
+  dueDate?: string          // ISO 8601 date string
+  priority?: number
+  processInstanceKey?: string
+  processDefinitionKey?: string
+  formKey?: string
+}
+```
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@bpmnkit/core`](https://www.npmjs.com/package/@bpmnkit/core) | BPMN/DMN/Form parser, builder, layout engine |
+| [`@bpmnkit/canvas`](https://www.npmjs.com/package/@bpmnkit/canvas) | Zero-dependency SVG BPMN viewer |
+| [`@bpmnkit/editor`](https://www.npmjs.com/package/@bpmnkit/editor) | Full-featured interactive BPMN editor |
+| [`@bpmnkit/engine`](https://www.npmjs.com/package/@bpmnkit/engine) | Lightweight BPMN process execution engine |
+| [`@bpmnkit/feel`](https://www.npmjs.com/package/@bpmnkit/feel) | FEEL expression language parser & evaluator |
+| [`@bpmnkit/plugins`](https://www.npmjs.com/package/@bpmnkit/plugins) | 22 composable canvas plugins |
+| [`@bpmnkit/operate`](https://www.npmjs.com/package/@bpmnkit/operate) | Monitoring and operations frontend for Camunda 8 |
+| [`@bpmnkit/api`](https://www.npmjs.com/package/@bpmnkit/api) | Camunda 8 REST API TypeScript client |
+| [`@bpmnkit/ascii`](https://www.npmjs.com/package/@bpmnkit/ascii) | Render BPMN diagrams as Unicode ASCII art |
+| [`@bpmnkit/ui`](https://www.npmjs.com/package/@bpmnkit/ui) | Shared design tokens and UI components |
+| [`@bpmnkit/profiles`](https://www.npmjs.com/package/@bpmnkit/profiles) | Shared auth, profile storage, and client factories for CLI & proxy |
+| [`@bpmnkit/connector-gen`](https://www.npmjs.com/package/@bpmnkit/connector-gen) | Generate connector templates from OpenAPI specs |
+| [`@bpmnkit/cli`](https://www.npmjs.com/package/@bpmnkit/cli) | Camunda 8 command-line interface (casen) |
+| [`@bpmnkit/proxy`](https://www.npmjs.com/package/@bpmnkit/proxy) | Local AI bridge and Camunda API proxy server |
+| [`@bpmnkit/cli-sdk`](https://www.npmjs.com/package/@bpmnkit/cli-sdk) | Plugin authoring SDK for the casen CLI |
+| [`@bpmnkit/create-casen-plugin`](https://www.npmjs.com/package/@bpmnkit/create-casen-plugin) | Scaffold a new casen CLI plugin in seconds |
+| [`@bpmnkit/casen-report`](https://www.npmjs.com/package/@bpmnkit/casen-report) | HTML reports from Camunda 8 incident and SLA data |
+| [`@bpmnkit/casen-worker-http`](https://www.npmjs.com/package/@bpmnkit/casen-worker-http) | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data |
+| [`@bpmnkit/casen-worker-ai`](https://www.npmjs.com/package/@bpmnkit/casen-worker-ai) | AI task worker — classify, summarize, extract, and decide using Claude |
+
+## License
+
+[MIT](https://github.com/bpmnkit/monorepo/blob/main/LICENSE) © BPMN Kit — made by [u11g](https://u11g.com)
+
+<div align="center">
+  <a href="https://bpmnkit.com"><img src="https://bpmnkit.com/favicon.svg" width="32" height="32" alt="BPMN Kit"></a>
+</div>

package/dist/actions.d.ts

@@ -0,0 +1,11 @@
+interface TaskActionOptions {
+    proxyUrl: string;
+    profile: string | null;
+    taskKey: string;
+}
+export declare function claimTask(options: TaskActionOptions, assignee: string): Promise<void>;
+export declare function unclaimTask(options: TaskActionOptions): Promise<void>;
+export declare function completeTask(options: TaskActionOptions, variables: Record<string, unknown>): Promise<void>;
+export declare function fetchTaskForm(proxyUrl: string, profile: string | null, taskKey: string): Promise<unknown>;
+export {};
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.js

@@ -0,0 +1,49 @@
+function buildHeaders(profile) {
+    const headers = {
+        "content-type": "application/json",
+        accept: "application/json",
+    };
+    if (profile)
+        headers["x-profile"] = profile;
+    return headers;
+}
+async function proxyPost(proxyUrl, path, profile, body) {
+    const res = await fetch(`${proxyUrl}${path}`, {
+        method: "POST",
+        headers: buildHeaders(profile),
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`HTTP ${res.status}${text ? `: ${text}` : ""}`);
+    }
+}
+async function proxyDelete(proxyUrl, path, profile) {
+    const res = await fetch(`${proxyUrl}${path}`, {
+        method: "DELETE",
+        headers: buildHeaders(profile),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`HTTP ${res.status}${text ? `: ${text}` : ""}`);
+    }
+}
+export async function claimTask(options, assignee) {
+    return proxyPost(options.proxyUrl, `/api/user-tasks/${options.taskKey}/assignment`, options.profile, { assignee });
+}
+export async function unclaimTask(options) {
+    return proxyDelete(options.proxyUrl, `/api/user-tasks/${options.taskKey}/assignment`, options.profile);
+}
+export async function completeTask(options, variables) {
+    return proxyPost(options.proxyUrl, `/api/user-tasks/${options.taskKey}/completion`, options.profile, { variables });
+}
+export async function fetchTaskForm(proxyUrl, profile, taskKey) {
+    const headers = { accept: "application/json" };
+    if (profile)
+        headers["x-profile"] = profile;
+    const res = await fetch(`${proxyUrl}/api/user-tasks/${taskKey}/form`, { headers });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return res.json();
+}
+//# sourceMappingURL=actions.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createUserTaskWidget } from "./widget.js";
+export type { UserTask, UserTaskWidgetApi, UserTaskWidgetOptions } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createUserTaskWidget } from "./widget.js";
+//# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+import type { Theme } from "@bpmnkit/ui";
+export interface UserTask {
+    userTaskKey: string;
+    name?: string;
+    assignee?: string;
+    candidateGroups?: string[];
+    dueDate?: string;
+    priority?: number;
+    processInstanceKey?: string;
+    processDefinitionKey?: string;
+    formKey?: string;
+}
+export interface UserTaskWidgetOptions {
+    /** The container element to render the widget into. */
+    container: HTMLElement;
+    /** The user task to display. */
+    task: UserTask;
+    /** Base URL of the proxy server. */
+    proxyUrl?: string;
+    /** Active profile name for x-profile header. */
+    profile?: string | null;
+    /** Visual theme. Defaults to "neon". */
+    theme?: Theme;
+    /** Called when the user completes the task. */
+    onComplete(variables: Record<string, unknown>): void;
+    /** Called when the user claims the task. */
+    onClaim(): void;
+    /** Called when the user unclaims the task. */
+    onUnclaim(): void;
+    /** Called when the user rejects/returns the task. */
+    onReject?(reason: string): void;
+}
+export interface UserTaskWidgetApi {
+    /** Update the displayed task. */
+    setTask(task: UserTask): void;
+    /** Remove the widget from the DOM and clean up. */
+    destroy(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/widget.d.ts

@@ -0,0 +1,3 @@
+import type { UserTaskWidgetApi, UserTaskWidgetOptions } from "./types.js";
+export declare function createUserTaskWidget(options: UserTaskWidgetOptions): UserTaskWidgetApi;
+//# sourceMappingURL=widget.d.ts.map

package/dist/widget.js

@@ -0,0 +1,228 @@
+import { FormViewer } from "@bpmnkit/plugins/form-viewer";
+import { applyTheme, injectUiStyles } from "@bpmnkit/ui";
+import { claimTask, completeTask, fetchTaskForm, unclaimTask } from "./actions.js";
+function el(tag, className, text) {
+    const e = document.createElement(tag);
+    e.className = className;
+    if (text !== undefined)
+        e.textContent = text;
+    return e;
+}
+const WIDGET_CSS = `
+.ut-root { font-family: var(--bpmnkit-font, system-ui, sans-serif); color: var(--bpmnkit-fg, #1a1a2e); }
+.ut-header { padding: 16px; border-bottom: 1px solid var(--bpmnkit-border, #d0d0e8); }
+.ut-name { font-size: 18px; font-weight: 600; margin-bottom: 8px; }
+.ut-meta { display: flex; gap: 12px; font-size: 13px; color: var(--bpmnkit-fg-muted, #6666a0); }
+.ut-meta-item { display: flex; align-items: center; gap: 4px; }
+.ut-overdue { color: var(--bpmnkit-danger, #dc2626); }
+.ut-form { padding: 16px; flex: 1; overflow-y: auto; }
+.ut-form-placeholder { padding: 32px; text-align: center; color: var(--bpmnkit-fg-muted, #6666a0); font-size: 14px; }
+.ut-actions { display: flex; gap: 8px; padding: 12px 16px; border-top: 1px solid var(--bpmnkit-border, #d0d0e8); }
+.ut-btn { padding: 6px 14px; border-radius: 6px; font-size: 13px; cursor: pointer; border: 1px solid transparent; transition: opacity 0.15s; }
+.ut-btn:hover { opacity: 0.85; }
+.ut-btn:disabled { opacity: 0.4; cursor: not-allowed; }
+.ut-btn-primary { background: var(--bpmnkit-accent, #1a56db); color: var(--bpmnkit-accent-fg, #fff); }
+.ut-btn-secondary { background: transparent; border-color: var(--bpmnkit-border, #d0d0e8); color: var(--bpmnkit-fg, #1a1a2e); }
+.ut-btn-danger { background: var(--bpmnkit-danger, #dc2626); color: #fff; }
+.ut-error { padding: 8px 12px; background: color-mix(in srgb, var(--bpmnkit-danger, #dc2626) 15%, transparent); color: var(--bpmnkit-danger, #dc2626); border-radius: 4px; font-size: 13px; margin: 0 16px 8px; }
+`;
+function injectWidgetStyles() {
+    const id = "bpmnkit-user-tasks-css";
+    if (document.getElementById(id))
+        return;
+    const style = document.createElement("style");
+    style.id = id;
+    style.textContent = WIDGET_CSS;
+    document.head.appendChild(style);
+}
+export function createUserTaskWidget(options) {
+    injectUiStyles();
+    injectWidgetStyles();
+    const { container, proxyUrl = "http://localhost:3033", profile = null, theme = "neon", onComplete, onClaim, onUnclaim, onReject, } = options;
+    // Create root element
+    const root = el("div", "ut-root");
+    applyTheme(root, theme);
+    root.style.display = "flex";
+    root.style.flexDirection = "column";
+    root.style.height = "100%";
+    container.appendChild(root);
+    // State
+    let currentTask = options.task;
+    let formViewer = null;
+    let formVariables = {};
+    // Error area
+    const errorEl = el("div", "ut-error");
+    errorEl.style.display = "none";
+    // Header
+    const header = el("div", "ut-header");
+    const nameEl = el("div", "ut-name");
+    const metaEl = el("div", "ut-meta");
+    header.appendChild(nameEl);
+    header.appendChild(metaEl);
+    root.appendChild(header);
+    root.appendChild(errorEl);
+    // Form area
+    const formArea = el("div", "ut-form");
+    const formContainer = el("div", "");
+    formArea.appendChild(formContainer);
+    root.appendChild(formArea);
+    // Actions
+    const actionsEl = el("div", "ut-actions");
+    const claimBtn = el("button", "ut-btn ut-btn-secondary", "Claim");
+    claimBtn.type = "button";
+    const unclaimBtn = el("button", "ut-btn ut-btn-secondary", "Unclaim");
+    unclaimBtn.type = "button";
+    const completeBtn = el("button", "ut-btn ut-btn-primary", "Complete");
+    completeBtn.type = "button";
+    const rejectBtn = el("button", "ut-btn ut-btn-danger", "Reject");
+    rejectBtn.type = "button";
+    if (!onReject)
+        rejectBtn.style.display = "none";
+    actionsEl.appendChild(claimBtn);
+    actionsEl.appendChild(unclaimBtn);
+    actionsEl.appendChild(completeBtn);
+    if (onReject)
+        actionsEl.appendChild(rejectBtn);
+    root.appendChild(actionsEl);
+    function showError(msg) {
+        errorEl.textContent = msg;
+        errorEl.style.display = "block";
+    }
+    function clearError() {
+        errorEl.style.display = "none";
+    }
+    function renderTask(task) {
+        nameEl.textContent = task.name ?? `Task ${task.userTaskKey}`;
+        metaEl.innerHTML = "";
+        if (task.assignee) {
+            const assigneeItem = el("span", "ut-meta-item");
+            assigneeItem.textContent = `Assigned to ${task.assignee}`;
+            metaEl.appendChild(assigneeItem);
+        }
+        if (task.dueDate) {
+            const due = new Date(task.dueDate);
+            const overdue = due < new Date();
+            const dueItem = el("span", overdue ? "ut-meta-item ut-overdue" : "ut-meta-item");
+            dueItem.textContent = `Due: ${due.toLocaleDateString()}${overdue ? " (overdue)" : ""}`;
+            metaEl.appendChild(dueItem);
+        }
+        if (task.priority !== undefined) {
+            const priorityItem = el("span", "ut-meta-item");
+            priorityItem.textContent = `Priority: ${task.priority}`;
+            metaEl.appendChild(priorityItem);
+        }
+        // Update button states
+        claimBtn.disabled = !!task.assignee;
+        unclaimBtn.disabled = !task.assignee;
+        // Load form
+        void loadForm(task);
+    }
+    async function loadForm(task) {
+        // Clean up existing viewer
+        if (formViewer) {
+            formViewer.destroy();
+            formViewer = null;
+        }
+        formContainer.innerHTML = "";
+        try {
+            const formData = await fetchTaskForm(proxyUrl, profile, task.userTaskKey);
+            // Camunda v2 returns { schema: Record<string,unknown>, ... }
+            // Some versions send schema as a JSON string instead of an object
+            let formDef = formData;
+            if (formData && typeof formData === "object" && "schema" in formData) {
+                const raw = formData.schema;
+                if (raw && typeof raw === "object") {
+                    formDef = raw;
+                }
+                else if (typeof raw === "string") {
+                    try {
+                        formDef = JSON.parse(raw);
+                    }
+                    catch {
+                        formDef = null;
+                    }
+                }
+            }
+            if (formDef && typeof formDef === "object" && "components" in formDef) {
+                const fvTheme = theme === "light" ? "light" : "dark";
+                formViewer = new FormViewer({ container: formContainer, theme: fvTheme });
+                formViewer.load(formDef);
+            }
+            else {
+                const placeholder = el("div", "ut-form-placeholder", "No form associated with this task.");
+                formContainer.appendChild(placeholder);
+            }
+        }
+        catch {
+            const placeholder = el("div", "ut-form-placeholder", "No form schema found or form is embedded in the process.");
+            formContainer.appendChild(placeholder);
+        }
+    }
+    // Event handlers
+    claimBtn.addEventListener("click", () => {
+        claimBtn.disabled = true;
+        claimBtn.textContent = "Claiming...";
+        claimTask({ proxyUrl, profile, taskKey: currentTask.userTaskKey }, "studio-user")
+            .then(() => {
+            clearError();
+            onClaim();
+        })
+            .catch((err) => {
+            showError(`Claim failed: ${err instanceof Error ? err.message : String(err)}`);
+        })
+            .finally(() => {
+            claimBtn.textContent = "Claim";
+        });
+    });
+    unclaimBtn.addEventListener("click", () => {
+        unclaimBtn.disabled = true;
+        unclaimBtn.textContent = "Unclaiming...";
+        unclaimTask({ proxyUrl, profile, taskKey: currentTask.userTaskKey })
+            .then(() => {
+            clearError();
+            onUnclaim();
+        })
+            .catch((err) => {
+            showError(`Unclaim failed: ${err instanceof Error ? err.message : String(err)}`);
+        })
+            .finally(() => {
+            unclaimBtn.textContent = "Unclaim";
+        });
+    });
+    completeBtn.addEventListener("click", () => {
+        completeBtn.disabled = true;
+        completeBtn.textContent = "Completing...";
+        completeTask({ proxyUrl, profile, taskKey: currentTask.userTaskKey }, formVariables)
+            .then(() => {
+            clearError();
+            onComplete(formVariables);
+        })
+            .catch((err) => {
+            showError(`Complete failed: ${err instanceof Error ? err.message : String(err)}`);
+            completeBtn.disabled = false;
+        })
+            .finally(() => {
+            completeBtn.textContent = "Complete";
+        });
+    });
+    rejectBtn.addEventListener("click", () => {
+        const reason = window.prompt("Reason for rejection (optional):", "") ?? "";
+        if (onReject)
+            onReject(reason);
+    });
+    // Initial render
+    renderTask(currentTask);
+    return {
+        setTask(task) {
+            currentTask = task;
+            formVariables = {};
+            renderTask(task);
+        },
+        destroy() {
+            formViewer?.destroy();
+            formViewer = null;
+            root.remove();
+        },
+    };
+}
+//# sourceMappingURL=widget.js.map

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@bpmnkit/user-tasks",
+	"version": "0.0.1",
+	"description": "Embeddable user task widget for Camunda 8 — form rendering, claim/complete actions, zero dependencies",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": ["LICENSE", "README.md", "dist/**/*.js", "dist/**/*.d.ts"],
+	"scripts": {
+		"build": "tsc",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check ."
+	},
+	"dependencies": {
+		"@bpmnkit/api": "workspace:*",
+		"@bpmnkit/core": "workspace:*",
+		"@bpmnkit/plugins": "workspace:*",
+		"@bpmnkit/ui": "workspace:*"
+	},
+	"keywords": [
+		"bpmn",
+		"camunda",
+		"user-tasks",
+		"workflow",
+		"form",
+		"task-management",
+		"typescript"
+	],
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/bpmnkit/monorepo"
+	},
+	"homepage": "https://bpmnkit.com",
+	"bugs": {
+		"url": "https://github.com/bpmnkit/monorepo/issues"
+	}
+}