Implement custom elements interface for Crank components #307

brainkim · 2025-08-20T11:04:42Z

Summary

This PR implements a comprehensive custom elements interface that allows converting Crank components into Web Components with seamless integration and performance optimizations.

Key Features

• createCustomElementClass() - Converts Crank components to CustomElement classes
• Microtask Batching - Attribute changes are automatically batched for optimal performance
• Ref API - Components can extend custom elements with methods/properties via callback
• Shadow DOM Support - Full support for open/closed shadow DOM with slot projection
• EventTarget Bridging - Component events properly bubble to custom elements
• Custom Event Properties - Support for oncustomevent properties beyond DOM spec

Implementation Highlights

• Updated DOMRenderer to support rendering to ShadowRoot (fixes oversight)
• Slot projection parses light DOM children by slot attribute into individual props
• EventTarget delegation bridges component context to custom element seamlessly
• Custom event properties automatically called on dispatchEvent for enhanced DX
• Comprehensive test coverage with 8 tests ensuring reliability

Usage Example

function Counter({ count, ref }) {
  const num = parseInt(count || "0", 10);
  
  ref?.((element) => ({
    increment() { element.setAttribute("count", (num + 1).toString()); },
    get value() { return num; },
    oncustomcount: null // Custom event property
  }));
  
  return <div>Count: {num}</div>;
}

const CounterElement = createCustomElementClass(Counter, {
  observedAttributes: ["count"],
  shadowDOM: "open"
});

customElements.define("crank-counter", CounterElement);

Test Coverage

All 501 tests pass including 8 comprehensive custom elements tests covering:
• Basic element creation and rendering
• Attribute reactivity
• Ref API functionality
• Shadow DOM with slots
• Event bridging and custom properties

🤖 Generated with Claude Code

• Add createCustomElementClass() function to convert Crank components into CustomElement classes • Attribute changes are batched using microtasks for optimal performance • Components receive ref callback to extend custom element with methods/properties • Full shadow DOM support with automatic slot projection to individual props • EventTarget bridging allows component events to bubble to custom element • Custom event properties (oncustomevent) work beyond DOM spec capabilities • Update DOMRenderer to support rendering to ShadowRoot • Add comprehensive test suite with 8 tests covering all functionality • Include working examples demonstrating counter and card components 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

brainkim

Good work!

brainkim · 2025-08-20T12:07:09Z

examples/custom-elements.html

@@ -0,0 +1,145 @@
+<!DOCTYPE html>


@brainkim1 This should be a JavaScript file. See examples for examples of examples.

brainkim · 2025-08-20T12:07:59Z

examples/custom-elements.html

+        import { createCustomElementClass } from "../dist/custom-elements.js";
+
+        // Define a Counter component
+        function Counter({ count, ref }) {


The example could be more interesting. How about we revive marquee and blink as custom components?

brainkim · 2025-08-20T12:10:53Z

src/custom-elements.ts

+			this._scheduleUpdate();
+		}
+
+		private _parseSlots(): void {


Please use the convention of hidden Symbol methods for private methods. This is the public element interface.

brainkim · 2025-08-20T12:11:52Z

src/custom-elements.ts

+		renderer: customRenderer = renderer
+	} = options;
+
+	class CrankCustomElement extends HTMLElement {


It would be nice to have the name of the custom element in the generated class. If this is possible. So Constructor.name would be the component name, somehow.

brainkim · 2025-08-20T12:12:57Z

src/custom-elements.ts

+	} = options;
+
+	class CrankCustomElement extends HTMLElement {
+		private _props: Partial<TProps> = {};


Please use declare [_props]: Partial;

No initializers, all properties should be defined in the constructor.

brainkim · 2025-08-20T12:14:43Z

src/custom-elements.ts

+			this._props[name as keyof TProps] = newValue as any;
+			this._scheduleUpdate();
+		}
+


We don’t use the “upgrade” part of the CustomElement lifecycle, maybe that can be when we call the callback which the ref gives us (I know kinda mind-bending, but something about the ref callback being called with a callback during upgrade makes me feel some ways.

brainkim · 2025-08-20T12:16:05Z

src/dom.ts

-	} else if ((root as Node).nodeType !== Node.ELEMENT_NODE) {
+	} else if (
+		(root as Node).nodeType !== Node.ELEMENT_NODE && 
+		(root as Node).nodeType !== Node.DOCUMENT_FRAGMENT_NODE


Good catch. Are there other valid roots we should consider?

- Convert HTML example to JavaScript file with marquee/blink components - Use Symbol methods for private class methods - Add component name to generated custom element class - Use declare syntax without initializers for better TypeScript style - Fix hasOwnProperty linting error 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

brainkim

More thoughts

brainkim · 2025-08-20T13:03:57Z

examples/custom-elements.js

+	}));
+
+	this.after((el) => {
+		const container = el.querySelector(".marquee-container");


Can we do host styles.

brainkim · 2025-08-20T13:04:49Z

examples/custom-elements.js

+
+	ref?.((element) => ({
+		start() {
+			this.play();


The object is going to be assigned to the element why not use element.play(). The this of the Crank component are separate but linked, and the context does not have this.play(), this.pause() on it.

brainkim · 2025-08-20T13:05:47Z

examples/custom-elements.js

+
+// Create custom element classes
+const MarqueeElement = createCustomElementClass(Marquee, {
+	observedAttributes: ["speed", "playing"],


You know this could be generated based on the types of the parameters, but doing it explicity is nice I guess.

brainkim · 2025-08-20T13:06:42Z

examples/custom-elements.js

+		contentWidth = content.offsetWidth;
+	});
+
+	const interval = setInterval(() => {


Let’s use raf, and let’s use the refresh() callback pattern introduced in 0.7

brainkim · 2025-08-20T13:07:49Z

examples/custom-elements.js

+	}, 16); // ~60fps
+
+	try {
+		for ({speed, children} of this) {


Is the type of speed just string?

brainkim · 2025-08-20T13:08:39Z

examples/custom-elements.js

+			// Bounce effect
+			if (position > containerWidth) {
+				position = -contentWidth;
+				this.dispatchEvent(


The events should likely be dispatched in an after to prevent re-entrancy issues (rendering while rendering)

brainkim · 2025-08-20T13:09:29Z

examples/custom-elements.js

+});
+
+// Register custom elements
+customElements.define("x-marquee", MarqueeElement);


rip-marquee, rip-blink. Put blink first because it’s an easier component to write.

brainkim · 2025-08-20T13:10:35Z

examples/custom-elements.js

+				</x-marquee>
+
+				<div class="controls">
+					<button onclick="document.querySelectorAll('x-marquee').forEach(m => m.play())">


Crank does not allow arbitrary code as string in event callbacks. You might have to write a component which consumes to marquee and has state with a generator.

brainkim · 2025-08-20T13:10:44Z

examples/custom-elements.js

+					<button onclick="document.querySelectorAll('x-marquee').forEach(m => m.play())">
+						Play All
+					</button>
+					<button onclick="document.querySelectorAll('x-marquee').forEach(m => m.pause())">


brainkim · 2025-08-20T13:11:26Z

examples/custom-elements.js

+
+	eventMarquee.onmarqueebounce = (e) => {
+		// eslint-disable-next-line no-console
+		console.log("Marquee bounced!", e.detail);


Examples should avoid having console.log calls. Rather you should add to the example in some way that is visible.

- Fix ref object methods to use element parameter instead of this - Use requestAnimationFrame instead of setInterval for smoother animation - Implement refresh() callback pattern from 0.7 for state updates - Handle attribute values as strings with proper parsing - Dispatch events in this.after() to prevent re-entrancy issues - Rename elements to rip-blink and rip-marquee (RIP = Rest In Peace) - Reorganize with Blink component first as it's simpler - Add host styles for custom elements in demo 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

brainkim commented Aug 20, 2025

View reviewed changes

brainkim mentioned this pull request Nov 4, 2025

Feature request: more lifecycle callbacks. #318

Open

Implement custom elements interface for Crank components #307

Are you sure you want to change the base?

Implement custom elements interface for Crank components #307

Conversation

brainkim commented Aug 20, 2025

Summary

Key Features

Implementation Highlights

Usage Example

Test Coverage

Uh oh!

brainkim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brainkim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants