@ripple-ts/compat-react 0.2.153

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ripple-ts/compat-react",
+  "version": "0.2.153",
+  "description": "Ripple compatibility layer for React",
+  "main": "src/index.js",
+  "author": "Dominic Gannaway",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ripple-TS/ripple.git",
+    "directory": "packages/compat-react"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./types": "./types/index.d.ts"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "ripple": "0.2.153"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "typescript": "^5.9.2"
+  }
+}

package/src/index.js

@@ -0,0 +1,196 @@
+/** @import { Tsx } from '../types' */
+/** @import { ReactNode } from 'react' */
+
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { useSyncExternalStore, useLayoutEffect, useRef, useState, Component } from 'react';
+import { createPortal } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import {
+	branch,
+	with_block,
+	proxy_props,
+	set,
+	render,
+	tracked,
+	get_tracked,
+	handle_error,
+} from 'ripple/internal/client';
+import { Context } from 'ripple';
+
+/** @type {Tsx} */
+const tsx = {
+	jsx,
+	jsxs,
+	Fragment,
+};
+
+/** @type {Context<null | { portals: Map<any, any>, update: Function}>} */
+const PortalContext = new Context(null);
+
+/**
+ * @param {any[] | Map<any, any>} portals
+ */
+function map_portals(portals) {
+	return Array.from(portals.entries()).map(([el, { component, key }], i) => {
+		return createPortal(jsx(component, {}, key), el);
+	});
+}
+
+export function createReactCompat() {
+	const root_portals = new Map();
+	/** @type {{ portals: Map<any, any>, update: Function}} */
+	const root_portal_state = { portals: root_portals, update: () => {} };
+
+	return {
+		/**
+		 * @param {HTMLElement} node
+		 * @param {(tsx: Tsx) => ReactNode} children_fn
+		 */
+		createComponent(node, children_fn) {
+			const target_element = document.createElement('span');
+			target_element.style.display = 'contents';
+			node.before(target_element);
+
+			/** @type {(() => void) | undefined} */
+			let trigger;
+			/** @type {(() => void) | undefined} */
+			let teardown;
+			/** @type {ReactNode} */
+			let react_node;
+
+			const e = render(() => {
+				react_node = children_fn(tsx);
+				trigger?.();
+			});
+			// @ts-ignore
+			target_element.__ripple_block = e;
+
+			/**
+			 * @param {() => void} callback
+			 */
+			function subscribe(callback) {
+				trigger = callback;
+
+				return () => {
+					teardown?.();
+				};
+			}
+
+			function ReactCompat() {
+				return useSyncExternalStore(subscribe, () => react_node);
+			}
+
+			class ReactCompatBoundary extends Component {
+				state = { e: false };
+
+				static getDerivedStateFromError(error) {
+					return { e: true };
+				}
+
+				componentDidCatch(error) {
+					handle_error(error, e);
+				}
+
+				render() {
+					if (this.state?.e) {
+						return null;
+					}
+					return jsx(ReactCompat, {});
+				}
+			}
+
+			const key = Math.random().toString(36).substring(2, 9);
+			const { portals, update } = PortalContext.get() || root_portal_state;
+			portals.set(target_element, { component: ReactCompatBoundary, key });
+			update();
+		},
+
+		createRoot() {
+			const root_element = document.createElement('span');
+
+			function CompatRoot() {
+				const [, root_update] = useState(0);
+				root_portal_state.update = root_update;
+
+				return map_portals(root_portals);
+			}
+
+			const root = createRoot(root_element);
+			root.render(jsx(CompatRoot, {}));
+
+			return () => {
+				root.unmount();
+			};
+		},
+	};
+}
+
+/**
+ * @param {HTMLSpanElement} node
+ */
+function get_block_from_dom(node) {
+	/** @type {null | ParentNode} */
+	let current = node;
+	while (current) {
+		const b = /** @type {any} */ (current).__ripple_block;
+		if (b) {
+			return /** @type {any} */ (b);
+		}
+		current = current.parentNode;
+	}
+	return null;
+}
+
+/**
+ * @template P
+ * @param {{ component: (anchor: Node, props: any) => void; props?: P }} props
+ * @returns {React.JSX.Element}
+ */
+export function Ripple({ component, props }) {
+	const ref = useRef(null);
+	const tracked_props_ref = useRef(/** @type {any} */ (null));
+	const portals_ref = /** @type {React.MutableRefObject<Map<any, any> | null>} */ (useRef(null));
+	const [, update] = useState(0);
+
+	if (portals_ref.current === null) {
+		portals_ref.current = new Map();
+	}
+	const portals = portals_ref.current;
+
+	useLayoutEffect(() => {
+		const span = /** @type {HTMLSpanElement | null} */ (ref.current);
+		if (span === null) {
+			return;
+		}
+		const frag = document.createDocumentFragment();
+		const anchor = document.createTextNode('');
+		const block = get_block_from_dom(span);
+		const tracked_props = (tracked_props_ref.current = tracked(props || {}, block));
+		const proxied_props = proxy_props(() => get_tracked(tracked_props));
+		frag.append(anchor);
+
+		const b = with_block(block, () => {
+			PortalContext.set({ portals, update });
+			return branch(() => {
+				component(anchor, proxied_props);
+			});
+		});
+
+		span.append(frag);
+
+		return () => {
+			anchor.remove();
+		};
+	}, [component]);
+
+	useLayoutEffect(() => {
+		set(/** @type {any} */ (tracked_props_ref.current), props || {});
+	}, [props]);
+
+	return jsx(Fragment, {
+		children: [
+			jsx('span', { ref, style: { display: 'contents' } }, 'target'),
+			...map_portals(portals),
+		],
+	});
+}

package/tests/client.d.ts

@@ -0,0 +1,12 @@
+declare var container: HTMLDivElement;
+declare var error: string | undefined;
+declare function render(component: () => void): void;
+
+interface HTMLElement {
+	// We don't care about checking if it returned an element or null in tests
+	// because if it returned null, those tests will fail anyway. This
+	// typing drastically simplifies testing: you don't have to check if the
+	// query returned null or an actual element, and you don't have to do
+	// optional chaining everywhere (elem?.textContent)
+	querySelector(selectors: string): HTMLElement;
+}

package/tests/index.test.ripple

@@ -0,0 +1,304 @@
+import { track, flushSync } from 'ripple';
+import { act } from 'react';
+
+describe('compat-react', () => {
+	it('should render basic React JSX inside tsx:react tags', async () => {
+		component App() {
+			<div>
+				<h1>{'Hello from Ripple'}</h1>
+				<tsx:react>
+					<div className="react-content">
+						{'Hello from React'}
+					</div>
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const rippleHeading = container.querySelector('h1');
+		const reactDiv = container.querySelector('.react-content');
+		expect(rippleHeading).toBeTruthy();
+		expect(rippleHeading.textContent).toBe('Hello from Ripple');
+		expect(reactDiv).toBeTruthy();
+		expect(reactDiv.textContent).toBe('Hello from React');
+	});
+
+	it('should render React fragments inside tsx:react tags', async () => {
+		component App() {
+			<div>
+				<tsx:react>
+					<>
+						<span className="first">
+							{'First'}
+						</span>
+						<span className="second">
+							{'Second'}
+						</span>
+					</>
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const first = container.querySelector('.first');
+		const second = container.querySelector('.second');
+		expect(first).toBeTruthy();
+		expect(first.textContent).toBe('First');
+		expect(second).toBeTruthy();
+		expect(second.textContent).toBe('Second');
+	});
+
+	it('should render nested React components', async () => {
+		component App() {
+			<div>
+				<tsx:react>
+					<div className="wrapper">
+						<div className="inner">
+							<span className="content">
+								{'Nested content'}
+							</span>
+						</div>
+					</div>
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const wrapper = container.querySelector('.wrapper');
+		const inner = container.querySelector('.inner');
+		const content = container.querySelector('.content');
+		expect(wrapper).toBeTruthy();
+		expect(inner).toBeTruthy();
+		expect(content).toBeTruthy();
+		expect(content.textContent).toBe('Nested content');
+	});
+
+	it('should mix Ripple and React content', async () => {
+		component App() {
+			<div class="container">
+				<div class="ripple">{'This is Ripple'}</div>
+				<tsx:react>
+					<div className="react">
+						{'This is React'}
+					</div>
+				</tsx:react>
+				<div class="ripple-2">{'Back to Ripple'}</div>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const rippleDiv = container.querySelector('.ripple');
+		const reactDiv = container.querySelector('.react');
+		const rippleDiv2 = container.querySelector('.ripple-2');
+		expect(rippleDiv).toBeTruthy();
+		expect(rippleDiv.textContent).toBe('This is Ripple');
+		expect(reactDiv).toBeTruthy();
+		expect(reactDiv.textContent).toBe('This is React');
+		expect(rippleDiv2).toBeTruthy();
+		expect(rippleDiv2.textContent).toBe('Back to Ripple');
+	});
+
+	it('should handle multiple tsx:react blocks', async () => {
+		component App() {
+			<div>
+				<tsx:react>
+					<div className="react-1">
+						{'React Block 1'}
+					</div>
+				</tsx:react>
+				<div class="ripple-middle">{'Ripple in between'}</div>
+				<tsx:react>
+					<div className="react-2">
+						{'React Block 2'}
+					</div>
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const react1 = container.querySelector('.react-1');
+		const middle = container.querySelector('.ripple-middle');
+		const react2 = container.querySelector('.react-2');
+		expect(react1).toBeTruthy();
+		expect(react1.textContent).toBe('React Block 1');
+		expect(middle).toBeTruthy();
+		expect(middle.textContent).toBe('Ripple in between');
+		expect(react2).toBeTruthy();
+		expect(react2.textContent).toBe('React Block 2');
+	});
+
+	it('should handle React components with attributes', async () => {
+		component App() {
+			<div>
+				<tsx:react>
+					<div className="react" id="test-id">
+						<span>
+							{'Content'}
+						</span>
+					</div>
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const reactDiv = container.querySelector('.react');
+		expect(reactDiv).toBeTruthy();
+		expect(reactDiv.id).toBe('test-id');
+		expect(reactDiv.querySelector('span').textContent).toBe('Content');
+	});
+
+	it('should handle nested fragments', async () => {
+		component App() {
+			<div>
+				<tsx:react>
+					<>
+						<div className="outer">
+							{'Outer'}
+						</div>
+						<>
+							<div className="inner">
+								{'Inner'}
+							</div>
+						</>
+					</>
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const outer = container.querySelector('.outer');
+		const inner = container.querySelector('.inner');
+		expect(outer).toBeTruthy();
+		expect(outer.textContent).toBe('Outer');
+		expect(inner).toBeTruthy();
+		expect(inner.textContent).toBe('Inner');
+	});
+
+	it('should handle complex nested structures', async () => {
+		component App() {
+			<div>
+				<tsx:react>
+					<div className="list">
+						<ul>
+							<li>
+								{'Item 1'}
+							</li>
+							<li>
+								{'Item 2'}
+							</li>
+							<li>
+								{'Item 3'}
+							</li>
+						</ul>
+					</div>
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const list = container.querySelector('.list');
+		const items = container.querySelectorAll('li');
+		expect(list).toBeTruthy();
+		expect(items.length).toBe(3);
+		expect(items[0].textContent).toBe('Item 1');
+		expect(items[1].textContent).toBe('Item 2');
+		expect(items[2].textContent).toBe('Item 3');
+	});
+
+	it('should handle empty fragments', async () => {
+		component App() {
+			<div>
+				<tsx:react>
+					<></>
+				</tsx:react>
+				<div class="after">{'After empty fragment'}</div>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const after = container.querySelector('.after');
+		expect(after).toBeTruthy();
+		expect(after.textContent).toBe('After empty fragment');
+	});
+
+	it('should work with Ripple reactivity', async () => {
+		component App() {
+			let count = track(0);
+			<div>
+				<div class="ripple-count">{@count}</div>
+				<button onClick={() => @count++}>{'Increment'}</button>
+				<tsx:react>
+					<div className="react-message">
+						{'React content is static'}
+					</div>
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const rippleCount = container.querySelector('.ripple-count');
+		const button = container.querySelector('button');
+		const reactMessage = container.querySelector('.react-message');
+		expect(rippleCount.textContent).toBe('0');
+		expect(reactMessage.textContent).toBe('React content is static');
+		button.click();
+		flushSync();
+		expect(rippleCount.textContent).toBe('1');
+		expect(reactMessage.textContent).toBe('React content is static');
+		button.click();
+		flushSync();
+		expect(rippleCount.textContent).toBe('2');
+	});
+
+	it('should handle a call expression at the top-level of a tsx:react block', async () => {
+		function renderReactText() {
+			return 'This is rendered from a React component!';
+		}
+
+		component App() {
+			<div>
+				<tsx:react>
+					{renderReactText()}
+				</tsx:react>
+			</div>
+		}
+
+		await act(async () => {
+			render(App);
+		});
+
+		const reactContent = container.querySelector('div > div');
+		expect(reactContent).toBeTruthy();
+		expect(reactContent.textContent).toBe('This is rendered from a React component!');
+	});
+});

package/tests/setup.js

@@ -0,0 +1,32 @@
+import { beforeEach, afterEach } from 'vitest';
+import { mount } from 'ripple';
+import { createReactCompat } from '../src/index.js';
+
+/**
+ * @param {() => void} component
+ */
+globalThis.render = function render(component) {
+	mount(component, {
+		target: /** @type {HTMLDivElement} */ (globalThis.container),
+		compat: {
+			react: createReactCompat(),
+		},
+	});
+};
+
+beforeEach(() => {
+	globalThis.container = /** @type {HTMLDivElement} */ (document.createElement('div'));
+	document.body.appendChild(globalThis.container);
+
+	globalThis.error = undefined;
+});
+
+afterEach(() => {
+	// Container is guaranteed to exist in all tests, so it was easier to type it without undefined.
+	// And when we unset it, we just type-cast it to HTMLDivElement to avoid TS errors, because we
+	// know it's guaranteed to exist in the next test again.
+	document.body.removeChild(/** @type {HTMLDivElement} */ (globalThis.container));
+	globalThis.container = /** @type {HTMLDivElement} */ (/** @type {unknown} */ (undefined));
+
+	globalThis.error = undefined;
+});

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "target": "esnext",
+    "noEmit": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "noEmitOnError": true,
+    "noErrorTruncation": true,
+    "allowSyntheticDefaultImports": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node", "vitest/globals"],
+    "jsx": "preserve",
+    "jsxImportSource": "ripple",
+    "strict": true,
+    "allowJs": true,
+    "checkJs": true
+  },
+  "include": [
+    "./*.js",
+    "./src/",
+    "./tests/**/*.test.ripple",
+    "./tests/**/*.d.ts",
+    "./tests/**/*.js"
+  ]
+}

package/types/index.d.ts

@@ -0,0 +1,14 @@
+import type { Component } from 'ripple';
+
+export type Tsx = {
+	jsx: typeof import('react/jsx-runtime').jsx;
+	jsxs: typeof import('react/jsx-runtime').jsxs;
+	Fragment: typeof import('react').Fragment;
+};
+
+export declare function createReactCompat(): {
+	createComponent(node: HTMLElement, children_fn: (tsx: Tsx) => any): void;
+	createRoot(): () => void | (() => void);
+};
+
+export declare function Ripple<P>(component: Component<P>, props?: P): React.JSX.Element;