fix: align delegated events with dom-expressions roots

ryansolid · cursoragent · ryansolid · commit adbdab301ec4 · 2026-05-15T11:47:59.000-07:00
Register Solid portal and custom element render roots with dom-expressions root-owned delegation so events retarget correctly across body portals and shadow DOM.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/.changeset/bump-dom-expressions-next-12.md b/.changeset/bump-dom-expressions-next-12.md
@@ -0,0 +1,8 @@
+---
+"@solidjs/web": patch
+"babel-preset-solid": patch
+---
+
+Bump dom-expressions and babel-plugin-jsx-dom-expressions to 0.50.0-next.12.
+
+This picks up root-owned delegated event targeting: `render()` and `hydrate()` own delegated listeners for their root containers while compiler-emitted `delegateEvents([...])` declares only the delegated event names needed by compiled JSX.
diff --git a/.changeset/fix-element-shadow-delegation.md b/.changeset/fix-element-shadow-delegation.md
@@ -0,0 +1,5 @@
+---
+"@solidjs/element": patch
+---
+
+Register custom element render roots for delegated events so handlers inside shadow DOM render roots fire correctly.
diff --git a/.changeset/web-portal-delegation-containers.md b/.changeset/web-portal-delegation-containers.md
@@ -0,0 +1,5 @@
+---
+"@solidjs/web": patch
+---
+
+Portal now participates in root-owned delegated events by registering outside-root mount points as listener containers for the owning render root.
diff --git a/documentation/solid-2.0/07-dom.md b/documentation/solid-2.0/07-dom.md
@@ -48,6 +48,19 @@ DOM behavior in Solid 2.0 follows HTML standards by default: attributes over pro
 <some-element enabled="true" />
 ```
 
+### Root-owned event delegation
+
+CamelCase JSX handlers such as `onClick` still use Solid's delegated event path, but delegation is now owned by render roots rather than by a document-global listener. `render()` / `hydrate()` install delegated listeners on their root container and dispose them when the root is disposed.
+
+This matters for roots that are embedded in a larger page or hosted by web components:
+
+- Rendering into a DOM element scopes delegated events to that root instead of the whole document.
+- Rendering into a `ShadowRoot` attaches delegated listeners to that shadow root.
+- `Portal` registers outside-root mount points as additional listener containers for the owning render root. Portal mounts already inside the root do not need extra listeners.
+- `event.stopPropagation()` inside a nested Solid root can prevent outer roots or host page code from observing the native event, while Solid avoids synthesizing events across unrelated roots.
+
+Compiler-emitted `delegateEvents([...])` now declares which delegated event names are needed; it no longer chooses the physical listener target. The physical listener lifetime is owned by render roots and any framework-provided listener containers.
+
 ### Directives via `ref` (and removal of `use:`)
 
 Solid 2.0 removes the `use:` directive namespace and instead treats “directives” as a first-class **ref** pattern. The `ref` prop becomes the single composition point for:
diff --git a/documentation/solid-2.0/MIGRATION.md b/documentation/solid-2.0/MIGRATION.md
@@ -549,6 +549,15 @@ const on = (type, handler, options) => el => el.addEventListener(type, handler,
 <button ref={on("click", handleClick, { capture: true })} />;
 ```
 
+Delegated events are now owned by render roots. `render()` and `hydrate()` install delegated listeners on their root container and clean them up when that root is disposed; compiler-emitted `delegateEvents([...])` only declares which event names are needed. This replaces the old document-global cleanup model.
+
+For most apps this is automatic. The visible differences are in nested roots, portals, and web component hosts:
+
+- Nested Solid roots no longer synthesize delegated handlers across each other's root boundaries.
+- Rendering into a `ShadowRoot` scopes delegated handlers to that shadow root, which is friendlier to web components.
+- `Portal` registers outside-root mount points as listener containers for the owning render root, so portal events still bubble through the logical Solid tree. Portal mounts already inside the root do not install extra listeners.
+- If you were calling `clearDelegatedEvents()`, remove it. Dispose the render root instead.
+
 ### Directives: `use:` → `ref` directive factories (two-phase pattern)
 
 ```jsx
diff --git a/examples/rendering/shared/src/components/Settings.tsx b/examples/rendering/shared/src/components/Settings.tsx
@@ -1,17 +1,37 @@
 import { createSignal, createUniqueId } from "solid-js";
+import { Portal } from "@solidjs/web";
 
 const Settings = () => {
   const [text, setText] = createSignal("Hi");
+  const [modalOpen, setModalOpen] = createSignal(false);
+  const [modalClicks, setModalClicks] = createSignal(0);
   const id = createUniqueId();
 
   return (
-    <>
+    <section onClick={() => modalOpen() && setModalClicks(c => c + 1)}>
       <h1>Settings</h1>
       <p>All that configuration you never really ever want to look at.</p>
       <label for={id}>Write:</label>
       <input type="text" id={id} value={text()} onInput={e => setText(e.currentTarget.value)} />
       <p>{text()}</p>
-    </>
+      <button type="button" onClick={() => setModalOpen(true)}>
+        Open body portal
+      </button>
+      <p>Portal logical clicks: {modalClicks()}</p>
+      {modalOpen() && (
+        <Portal>
+          <div class="modal-backdrop">
+            <div class="modal-card" role="dialog" aria-modal="true" aria-label="Settings portal">
+              <h2>Body Portal</h2>
+              <p>This modal is portaled to document.body.</p>
+              <button type="button" onClick={() => setModalOpen(false)}>
+                Close portal
+              </button>
+            </div>
+          </div>
+        </Portal>
+      )}
+    </section>
   );
 };
 
diff --git a/examples/rendering/shared/static/styles.css b/examples/rendering/shared/static/styles.css
@@ -73,4 +73,26 @@ a.link {
   display: block;
   margin-bottom: 0.5rem;
   color: #337ab7;
-}
+}
+.modal-backdrop {
+  position: fixed;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  background: rgba(0, 0, 0, 0.45);
+  z-index: 1000;
+}
+.modal-card {
+  width: min(420px, calc(100vw - 2rem));
+  padding: 1.5rem;
+  border-radius: 8px;
+  border: 1px solid #d0d7de;
+  background: white;
+  box-shadow: 0 18px 48px rgba(0, 0, 0, 0.25);
+  color: #444;
+  font-family: sans-serif;
+}
+.modal-card h2 {
+  margin-top: 0;
+  color: #337ab7;
+}
diff --git a/package.json b/package.json
@@ -36,12 +36,12 @@
     "@rollup/plugin-replace": "^5.0.2",
     "@types/node": "^25.0.8",
     "@vitest/coverage-v8": "^4.1.6",
-    "babel-plugin-jsx-dom-expressions": "0.50.0-next.11",
+    "babel-plugin-jsx-dom-expressions": "0.50.0-next.12",
     "babel-plugin-transform-rename-import": "^2.3.0",
     "coveralls": "^3.1.1",
     "csstype": "^3.1.0",
-    "dom-expressions": "0.50.0-next.11",
-    "hyper-dom-expressions": "0.50.0-next.11",
+    "dom-expressions": "0.50.0-next.12",
+    "hyper-dom-expressions": "0.50.0-next.12",
     "jsdom": "^25.0.1",
     "ncp": "^2.0.0",
     "npm-run-all": "^4.1.5",
@@ -52,7 +52,7 @@
     "rollup-plugin-copy": "^3.4.0",
     "seroval": "~1.5.0",
     "simple-git-hooks": "^2.8.1",
-    "sld-dom-expressions": "0.50.0-next.11",
+    "sld-dom-expressions": "0.50.0-next.12",
     "symlink-dir": "^5.0.1",
     "tsconfig-replace-paths": "^0.0.11",
     "turbo": "^2.0.0",
diff --git a/packages/babel-preset-solid/package.json b/packages/babel-preset-solid/package.json
@@ -18,7 +18,7 @@
     "test": "node test.js"
   },
   "dependencies": {
-    "babel-plugin-jsx-dom-expressions": "0.50.0-next.11"
+    "babel-plugin-jsx-dom-expressions": "0.50.0-next.12"
   },
   "peerDependencies": {
     "@babel/core": "^7.0.0",
diff --git a/packages/solid-element/package.json b/packages/solid-element/package.json
@@ -23,7 +23,8 @@
   "sideEffects": false,
   "scripts": {
     "clean": "rimraf dist/",
-    "build": "pnpm run clean && tsc"
+    "build": "pnpm run clean && tsc",
+    "test": "vitest run"
   },
   "dependencies": {
     "component-register": "^0.8.7"
diff --git a/packages/solid-element/src/index.ts b/packages/solid-element/src/index.ts
@@ -9,7 +9,7 @@ import {
 export { hot, getCurrentElement, noShadowDOM } from "component-register";
 export type ComponentType<T> = mComponentType<T>;
 import { createRoot, createSignal, runWithOwner } from "solid-js";
-import { insert } from "@solidjs/web";
+import { insert, registerDelegatedRoot, unregisterDelegatedRoot } from "@solidjs/web";
 
 function createProps<T extends object>(raw: T) {
   const keys = Object.keys(raw) as (keyof T)[];
@@ -53,11 +53,13 @@ function withSolid<T extends object>(ComponentType: ComponentType<T>): Component
           (key: string, val: any) => (props[key as keyof T] = val)
         );
         element.addReleaseCallback(() => {
+          unregisterDelegatedRoot(element.renderRoot as Node);
           (element.renderRoot as Node).textContent = "";
           dispose();
         });
 
         const comp = (ComponentType as FunctionComponent<T>)(props as T, options);
+        registerDelegatedRoot(element.renderRoot as Node);
         return insert(element.renderRoot, comp);
       });
     }
diff --git a/packages/solid-element/test/element.spec.tsx b/packages/solid-element/test/element.spec.tsx
@@ -0,0 +1,87 @@
+/**
+ * @jsxImportSource @solidjs/web
+ * @vitest-environment jsdom
+ */
+import { afterEach, describe, expect, test } from "vitest";
+import { createSignal, flush, onCleanup } from "solid-js";
+import { customElement } from "../src/index.js";
+
+const nextTag = (name: string) => `${name}-${crypto.randomUUID()}`;
+
+describe("solid-element", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  test("renders into a shadow root by default", () => {
+    const tag = nextTag("shadow-render");
+    customElement(tag, () => <span>Hello element</span>);
+
+    const element = document.createElement(tag);
+    document.body.append(element);
+
+    expect(element.shadowRoot!.innerHTML).toBe("<span>Hello element</span>");
+  });
+
+  test("updates rendered output when element properties change", () => {
+    const tag = nextTag("reactive-prop");
+    customElement(tag, { count: 0 }, props => <span>{props.count}</span>);
+
+    const element = document.createElement(tag) as HTMLElement & { count: number };
+    document.body.append(element);
+    element.count = 2;
+    flush();
+
+    expect(element.shadowRoot!.textContent).toBe("2");
+  });
+
+  test("parses observed attributes into reactive props", () => {
+    const tag = nextTag("reactive-attr");
+    customElement(tag, { label: "initial" }, props => <span>{props.label}</span>);
+
+    const element = document.createElement(tag);
+    element.setAttribute("label", "updated");
+    document.body.append(element);
+
+    expect(element.shadowRoot!.textContent).toBe("updated");
+  });
+
+  test("runs cleanup when the element disconnects", async () => {
+    const tag = nextTag("cleanup");
+    const [count, setCount] = createSignal(0);
+    let cleanups = 0;
+
+    customElement(tag, () => {
+      onCleanup(() => cleanups++);
+      return <span>{count()}</span>;
+    });
+
+    const element = document.createElement(tag);
+    document.body.append(element);
+    element.remove();
+    await Promise.resolve();
+    setCount(1);
+    flush();
+
+    expect(cleanups).toBe(1);
+    expect(element.shadowRoot!.textContent).toBe("");
+  });
+
+  test("delegated events work when rendering a custom element inside a shadow root", () => {
+    let clicks = 0;
+    const tag = nextTag("shadow-event");
+
+    customElement(tag, () => <button onClick={() => clicks++}>Click</button>);
+
+    const host = document.createElement("div");
+    const shadow = host.attachShadow({ mode: "open" });
+    const element = document.createElement(tag);
+    document.body.append(host);
+    shadow.append(element);
+
+    const button = element.shadowRoot!.querySelector("button")!;
+    button.dispatchEvent(new MouseEvent("click", { bubbles: true, composed: true }));
+
+    expect(clicks).toBe(1);
+  });
+});
diff --git a/packages/solid-element/vite.config.mjs b/packages/solid-element/vite.config.mjs
@@ -0,0 +1,30 @@
+/// <reference types="vitest" />
+
+import { defineConfig } from "vitest/config";
+import solidPlugin from "vite-plugin-solid";
+import { resolve } from "path";
+
+const rootDir = resolve(__dirname);
+
+export default defineConfig({
+  plugins: [solidPlugin()],
+  define: {
+    __DEV__: "true",
+    __TEST__: "true"
+  },
+  test: {
+    environment: "jsdom",
+    pool: "threads",
+    globals: true,
+    exclude: ["**/node_modules/**"]
+  },
+  resolve: {
+    conditions: ["development", "browser"],
+    alias: {
+      "@solidjs/signals": [resolve(rootDir, "../solid-signals/src")],
+      "solid-js": [resolve(rootDir, "../solid/src")],
+      rxcore: [resolve(rootDir, "../solid-web/src/core")],
+      "@solidjs/web": [resolve(rootDir, "../solid-web/src")]
+    }
+  }
+});
diff --git a/packages/solid-web/src/index.ts b/packages/solid-web/src/index.ts
@@ -6,7 +6,10 @@ import {
   MathMLElements,
   Namespaces,
   render as renderCore,
-  hydrate as hydrateCore
+  hydrate as hydrateCore,
+  registerDelegatedContainer,
+  unregisterDelegatedContainer,
+  getDelegatedRoot
 } from "./client.js";
 import {
   createComponent,
@@ -19,6 +22,7 @@ import {
   flush,
   $DEVCOMP,
   Component,
+  createEffect,
   createRenderEffect
 } from "solid-js";
 import type { JSX } from "./jsx.js";
@@ -205,8 +209,8 @@ export function Portal<T extends boolean = false, S extends boolean = false>(pro
   const treeMarker = document.createTextNode(""),
     startMarker = document.createTextNode(""),
     endMarker = document.createTextNode(""),
-    mount = () => createElementProxy(props.mount || document.body, treeMarker);
-  let content = createMemo(() => [startMarker, props.children] as unknown as JSX.Element);
+    mount = () => createElementProxy(props.mount || document.body, treeMarker),
+    content = createMemo(() => [startMarker, props.children] as unknown as JSX.Element);
 
   createRenderEffect<[Element, JSX.Element]>(
     () => [mount(), content()],
@@ -223,6 +227,14 @@ export function Portal<T extends boolean = false, S extends boolean = false>(pro
       };
     }
   );
+
+  createEffect(mount, m => {
+    const ownerRoot = getDelegatedRoot(treeMarker);
+    if (!ownerRoot || (ownerRoot as Node).contains(m)) return;
+    registerDelegatedContainer(m, ownerRoot);
+    return () => unregisterDelegatedContainer(m, ownerRoot);
+  });
+
   return treeMarker as unknown as JSX.Element;
 }
 
diff --git a/packages/solid-web/test/portal.spec.tsx b/packages/solid-web/test/portal.spec.tsx
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@solidjs/element": patch
 +---
++
 +Register custom element render roots for delegated events so handlers inside shadow DOM render roots fire correctly.