open-workflow-specification · lornakelly · Aug 4, 2026 · Jul 29, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/.changeset/add-vanilla-web-component-example.md b/.changeset/add-vanilla-web-component-example.md
@@ -0,0 +1,5 @@
+---
+"@openworkflowspec/vanilla-web-component-example": minor
+---
+
+Add a non-React host example for the Diagram Editor
diff --git a/.changeset/validate-color-mode-input.md b/.changeset/validate-color-mode-input.md
@@ -0,0 +1,5 @@
+---
+"@openworkflowspec/diagram-editor": patch
+---
+
+Validate colorMode input in useResolvedColorMode, falling back to "system" for unknown values.
diff --git a/examples/vanilla-web-component/.oxfmtrc.json b/examples/vanilla-web-component/.oxfmtrc.json
@@ -0,0 +1,3 @@
+{
+  "extends": ["../../.oxfmtrc.json"]
+}
diff --git a/examples/vanilla-web-component/.oxlintrc.json b/examples/vanilla-web-component/.oxlintrc.json
@@ -0,0 +1,3 @@
+{
+  "extends": ["../../.oxlintrc.json"]
+}
diff --git a/examples/vanilla-web-component/README.md b/examples/vanilla-web-component/README.md
@@ -0,0 +1,76 @@
+<!--
+   Copyright 2021-Present The Open Workflow Specification Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+# @openworkflowspec/vanilla-web-component-example
+
+This example demonstrates how to embed the `@openworkflowspec/diagram-editor` React component in a **non-React** host application using a Web Component.
+
+## Quick Start
+
+From the **repository root**:
+
+```bash
+pnpm install
+pnpm --filter @openworkflowspec/vanilla-web-component-example start
+```
+
+Browse http://localhost:6007
+
+## How It Works
+
+The wrapper in `src/diagram-editor-element.ts` defines a custom element `<openworkflowspec-diagram-editor>` that:
+
+1. Creates a React root inside itself
+2. Renders the `DiagramEditor` React component
+3. Re-renders when attributes or properties change
+4. Unmounts the React root on disconnect
+
+### HTMLElement attributes
+
+| Attribute / Property | Type                            | Default    | Description                                              |
+| -------------------- | ------------------------------- | ---------- | -------------------------------------------------------- |
+| `content` (property) | `string`                        | -          | Serverless Workflow specification in YAML or JSON format |
+| `locale`             | `string`                        | -          | Language locale for the editor UI                        |
+| `color-mode`         | `'light' \| 'dark' \| 'system'` | `"system"` | Color theme for the editor                               |
+| `read-only`          | boolean                         | -          | Enable read-only mode to prevent editing                 |
+
+### Usage
+
+```html
+<openworkflowspec-diagram-editor locale="en" read-only></openworkflowspec-diagram-editor>
+
+<script type="module">
+  import "./src/index.ts";
+
+  const editor = document.querySelector("openworkflowspec-diagram-editor");
+  editor.content = `document:
+  dsl: '1.0.3'
+  namespace: examples
+  name: my-workflow
+  version: '0.1.0'
+do:
+  - greet:
+      call: http
+      with:
+        method: get
+        endpoint:
+          uri: https://example.com`;
+</script>
+```
+
+### CSS
+
+The entry point (`src/index.ts`) imports `@openworkflowspec/diagram-editor/styles.css`. All editor styles are scoped under `.dec-root` with prefixed Tailwind classes.
diff --git a/examples/vanilla-web-component/index.html b/examples/vanilla-web-component/index.html
@@ -0,0 +1,57 @@
+<!doctype html>
+<!--
+  Copyright 2021-Present The Open Workflow Specification Authors
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Diagram Editor — Web Component Example</title>
+    <style>
+      body {
+        height: 100vh;
+      }
+
+      h1 {
+        margin: 16px;
+        font-size: 1.25rem;
+        font-weight: 600;
+        text-align: center;
+      }
+
+      openworkflowspec-diagram-editor {
+        display: block;
+        width: 80%;
+        height: 80%;
+        border: 1px solid black;
+        border-radius: 8px;
+        overflow: hidden;
+        margin: auto;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Diagram Editor — Web Component Example</h1>
+    <openworkflowspec-diagram-editor locale="en" read-only></openworkflowspec-diagram-editor>
+
+    <script type="module">
+      import "./src/index.ts";
+      import { sampleWorkflow } from "./src/sample-workflow.ts";
+
+      const editor = document.querySelector("openworkflowspec-diagram-editor");
+      editor.content = sampleWorkflow;
+    </script>
+  </body>
+</html>
diff --git a/examples/vanilla-web-component/package.json b/examples/vanilla-web-component/package.json
@@ -0,0 +1,48 @@
+{
+  "name": "@openworkflowspec/vanilla-web-component-example",
+  "version": "1.0.0",
+  "private": true,
+  "description": "non-React example embedding the open workflow diagram component",
+  "keywords": [],
+  "homepage": "https://github.com/open-workflow-specification/editor",
+  "bugs": {
+    "url": "https://github.com/open-workflow-specification/editor/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-workflow-specification/editor.git"
+  },
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --config .oxlintrc.json src/ tests/",
+    "format": "oxfmt --config .oxfmtrc.json",
+    "format:check": "oxfmt --config .oxfmtrc.json --check",
+    "clean": "rimraf ./dist",
+    "build:dev": "pnpm clean && tsc -p tsconfig.json && vite build",
+    "build:prod": "pnpm lint && pnpm clean && tsc -p tsconfig.json && vite build && pnpm test && pnpm test-e2e",
+    "test": "vitest run",
+    "start": "vite",
+    "test-e2e": "playwright test",
+    "test-e2e:ui": "playwright test --ui"
+  },
+  "dependencies": {
+    "@openworkflowspec/diagram-editor": "workspace:*",
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "devDependencies": {
+    "@playwright/test": "catalog:",
+    "@testing-library/dom": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "jsdom": "catalog:",
+    "oxfmt": "catalog:",
+    "oxlint": "catalog:",
+    "rimraf": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "catalog:"
+  }
+}
diff --git a/examples/vanilla-web-component/playwright.config.ts b/examples/vanilla-web-component/playwright.config.ts
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2021-Present The Open Workflow Specification Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "tests-e2e",
+
+  expect: {
+    timeout: 30000,
+  },
+
+  use: {
+    baseURL: "http://localhost:6007",
+  },
+
+  webServer: {
+    command: "pnpm start",
+    url: "http://localhost:6007",
+    reuseExistingServer: !process.env.CI,
+    timeout: 120 * 1000,
+  },
+});
diff --git a/examples/vanilla-web-component/src/diagram-editor-element.ts b/examples/vanilla-web-component/src/diagram-editor-element.ts
@@ -0,0 +1,73 @@
+/*
+ * Copyright 2021-Present The Open Workflow Specification Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// React is required internally by @openworkflowspec/diagram-editor.
+// This wrapper encapsulates it behind a standard Custom Element API,
+// so host applications don't need to interact with React directly.
+import { createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { DiagramEditor } from "@openworkflowspec/diagram-editor";
+import type { DiagramEditorProps, ColorMode } from "@openworkflowspec/diagram-editor";
+
+export class DiagramEditorElement extends HTMLElement {
+  static observedAttributes = ["locale", "color-mode", "read-only"];
+
+  private _root: Root | null = null;
+  private _mountPoint: HTMLDivElement | null = null;
+  private _content = "";
+
+  get content(): string {
+    return this._content;
+  }
+
+  set content(value: string) {
+    this._content = value;
+    this.render();
+  }
+
+  connectedCallback(): void {
+    this._mountPoint = document.createElement("div");
+    this._mountPoint.style.height = "100%";
+    this._mountPoint.dataset.testid = "diagram-editor-mount-point";
+    this.appendChild(this._mountPoint);
+    this._root = createRoot(this._mountPoint);
+    this.render();
+  }
+
+  disconnectedCallback(): void {
+    this._root?.unmount();
+    this._root = null;
+    this._mountPoint?.remove();
+    this._mountPoint = null;
+  }
+
+  attributeChangedCallback(): void {
+    this.render();
+  }
+
+  private render(): void {
+    if (!this._root) return;
+
+    const props: DiagramEditorProps = {
+      content: this._content,
+      locale: this.getAttribute("locale") ?? "en",
+      isReadOnly: this.hasAttribute("read-only"),
+      colorMode: (this.getAttribute("color-mode") as ColorMode) ?? "system",
+    };
+
+    this._root.render(createElement(DiagramEditor, props));
+  }
+}
diff --git a/examples/vanilla-web-component/src/index.ts b/examples/vanilla-web-component/src/index.ts
@@ -0,0 +1,22 @@
+/*
+ * Copyright 2021-Present The Open Workflow Specification Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import "@openworkflowspec/diagram-editor/styles.css";
+import { DiagramEditorElement } from "./diagram-editor-element";
+
+if (!customElements.get("openworkflowspec-diagram-editor")) {
+  customElements.define("openworkflowspec-diagram-editor", DiagramEditorElement);
+}