thunderous 0.0.4 → 0.2.0

package/README.md

@@ -34,21 +34,12 @@ const myStyleSheet = css`
   }
 `;
 
-const MyElement = customElement((params) => {
-  const { connectedCallback, refs, adoptStyleSheet } = params;
-
+const MyElement = customElement(({ customCallback, refs, adoptStyleSheet }) => {
   const [count, setCount] = createSignal(0);
-
-  connectedCallback(() => {
-    refs.increment.addEventListener('click', () => {
-      setCount(count() + 1);
-    });
-  });
-
+  const increment = customCallback(() => setCount(count() + 1));
   adoptStyleSheet(myStyleSheet);
-
   return html`
-    <button ref="increment">Increment</button>
+    <button onclick="${increment}">Increment</button>
     <output>${count}</output>
   `;
 });
@@ -74,7 +65,6 @@ const MyElement = customElement((params) => {
     disconnectedCallback,
     attributeChangedCallback,
   } = params;
-
   /* ... */
 });
 ```
@@ -90,7 +80,6 @@ const MyElement = customElement((params) => {
     formResetCallback,
     formStateRestoreCallback,
   } = params;
-
   /* ... */
 }, { formAssociated: true });
 ```
@@ -102,17 +91,10 @@ You can always define the internals the same as you usually would, and if for so
 
 <!-- prettier-ignore-start -->
 ```ts
-const MyElement = customElement((params) => {
-  const {
-    internals,
-    elementRef,
-    root,
-  } = params;
-
+const MyElement = customElement(({ internals, elementRef, root }) => {
   internals.ariaRequired = 'true';
   const childLink = elementRef.querySelector('a[href]'); // light DOM
   const innerLink = root.querySelector('a[href]'); // shadow DOM
-
   /* ... */
 }, { formAssociated: true });
 ```
@@ -137,11 +119,8 @@ const myStyleSheet = css`
   }
 `;
 
-const MyElement = customElement((params) => {
-  const { adoptStyleSheet } = params;
-
+const MyElement = customElement(({ adoptStyleSheet }) => {
   adoptStyleSheet(myStyleSheet);
-
   /* ... */
 });
 ```
@@ -157,19 +136,12 @@ Creating signals should look pretty familiar to most modern developers.
 
 <!-- prettier-ignore-start -->
 ```ts
-import { createSignal, customElement } from 'thunderous';
+import { createSignal } from 'thunderous';
 
-const MyElement = customElement(() => {
-  const [count, setCount] = createSignal(0);
-
-  console.log(count()); // 0
-
-  setCount(1);
-
-  console.log(count()) // 1
-
-  /* ... */
-});
+const [count, setCount] = createSignal(0);
+console.log(count()); // 0
+setCount(1);
+console.log(count()) // 1
 ```
 <!-- prettier-ignore-end -->
 
@@ -183,9 +155,7 @@ import { createSignal, customElement, html } from 'thunderous';
 
 const MyElement = customElement(() => {
   const [count, setCount] = createSignal(0);
-
   // presumably setCount() gets called
-
   return html`<output>${count}</output>`;
 });
 ```
@@ -199,22 +169,29 @@ By binding signals to templates, you allow fine-grained updates to be made direc
 
 ##### Attribute Signals
 
-Instead of worrying about the manual `observedAttributes` approach, each element is observed with a `MutationObserver` watching all attributes. All changes trigger the `attributeChangedCallback` and you can access all attributes as signals. This makes it much less cumbersome to write reactive attributes.
+By default, each element is observed with a `MutationObserver` watching all attributes. Changes to _any_ attribute trigger the `attributeChangedCallback` and you can access all attributes as signals. This makes it much less cumbersome to write reactive attributes.
 
 <!-- prettier-ignore-start -->
 ```ts
-const MyElement = customElement((params) => {
-  const { attrSignals } = params;
-
+const MyElement = customElement(({ attrSignals }) => {
   const [heading, setHeading] = attrSignals['my-heading'];
-
   // setHeading() will also update the attribute in the DOM.
-
   return html`<h2>${heading}</h2>`;
 });
 ```
 <!-- prettier-ignore-end -->
 
+However, the `MutationObserver` does impose a small performance tradeoff that may add up if you render a lot of elements. To better optimize for performance, you can pass `observedAttributes` to the options. Doing so will disable the `MutationObserver`, and only the observed attributes will trigger the `attributeChangedCallback`.
+
+<!-- prettier-ignore-start -->
+```ts
+const MyElement = customElement(({ attrSignals }) => {
+  const [heading, setHeading] = attrSignals['my-heading'];
+  return html`<h2>${heading}</h2>`;
+}, { observedAttributes: ['my-heading'] });
+```
+<!-- prettier-ignore-end -->
+
 Usage:
 
 ```html
@@ -223,33 +200,67 @@ Usage:
 
 > NOTICE: Since `attrSignals` is a `Proxy` object, _any_ property will return a signal and auto-bind it to the attribute it corresponds with.
 
-#### Refs
+##### Derived Signals
 
-Finally, the refs property exists for convenience to avoid manually querying the DOM. Since the DOM is only available after rendering, refs will only work in and after the `connectedCallback` method. This is the best place for event binding to occur.
+If you want to calculate a value based on another signal's value, you should use the `derived()` function. This signal will trigger its subscribers each time the signals inside change.
 
-<!-- prettier-ignore-start -->
 ```ts
-const MyElement = customElement((params) => {
-  const { connectedCallback, refs } = params;
+import { derived, createSignal } from 'thunderous';
 
-  const [count, setCount] = createSignal(0);
+const [count, setCount] = createSignal(0);
+const timesTen = derived(() => count() * 10);
+console.log(timesTen()); // 0
+setCount(10);
+console.log(timesTen()); // 100
+```
+
+##### Effects
+
+To run a callback each time a signal is changed, use the `createEffect()` function. Any signal used inside will trigger the callback when they're changed.
+
+```ts
+import { createEffect } from 'thunderous';
+
+/* ... */
+createEffect(() => {
+  console.log(count());
+});
+```
 
+#### Refs
+
+The refs property exists for convenience to avoid manually querying the DOM. Since the DOM is only available after rendering, refs will only work in and after the `connectedCallback` method.
+
+<!-- prettier-ignore-start -->
+```ts
+const MyElement = customElement(({ connectedCallback, refs }) => {
   connectedCallback(() => {
-    refs.increment.addEventListener('click', () => {
-      setCount(count() + 1);
-    });
+    console.log(refs.heading.textContent); // hello world
   });
+  return html`<h2 ref="heading">hello world</h2>`;
+});
+```
+<!-- prettier-ignore-end -->
 
+#### Event Binding
+
+While you could bind events in the `connectedCallback()` with `refs.button.addEventListener('click', handleClick)` for example, it may be more convenient to register a custom callback and bind it to the template.
+
+<!-- prettier-ignore-start -->
+```ts
+const MyElement = customElement(({ customCallback }) => {
+  const [count, setCount] = createSignal(0);
+  const increment = customCallback(() => setCount(count() + 1));
   return html`
-    <button ref="increment">Increment</button>
+    <button onclick="${increment}">Increment</button>
     <output>${count}</output>
   `;
 });
-
-MyElement.define('my-element');
 ```
 <!-- prettier-ignore-end -->
 
+> NOTICE: This uses the native HTML inline event-binding syntax. There is no special syntax for `on` attributes, because it simply renders a reference to `this.getRootNode().host` and extracts the callback from there.
+
 ### Defining Custom Elements
 
 The `customElement()` function allows you to author a web component, returning an `ElementResult` that has some helpful methods like `define()` and `eject()`.

package/dist/index.cjs

@@ -80,10 +80,11 @@ var createEffect = (fn) => {
 
 // src/custom-element.ts
 var DEFAULT_RENDER_OPTIONS = {
-  formAssociated: false
+  formAssociated: false,
+  observedAttributes: []
 };
 var customElement = (render, options) => {
-  const { formAssociated } = { ...DEFAULT_RENDER_OPTIONS, ...options };
+  const { formAssociated, observedAttributes } = { ...DEFAULT_RENDER_OPTIONS, ...options };
   class CustomElement extends HTMLElement {
     #attrSignals = {};
     #attributeChangedFns = /* @__PURE__ */ new Set();
@@ -93,9 +94,10 @@ var customElement = (render, options) => {
     #formDisabledCallbackFns = /* @__PURE__ */ new Set();
     #formResetCallbackFns = /* @__PURE__ */ new Set();
     #formStateRestoreCallbackFns = /* @__PURE__ */ new Set();
+    __customCallbackFns = /* @__PURE__ */ new Map();
     #shadowRoot = this.attachShadow({ mode: "closed" });
     #internals = this.attachInternals();
-    #observer = new MutationObserver((mutations) => {
+    #observer = observedAttributes.length > 0 ? null : new MutationObserver((mutations) => {
       for (const mutation of mutations) {
         const attrName = mutation.attributeName;
         if (mutation.type !== "attributes" || attrName === null) continue;
@@ -121,6 +123,11 @@ var customElement = (render, options) => {
         formDisabledCallback: (fn) => this.#formDisabledCallbackFns.add(fn),
         formResetCallback: (fn) => this.#formResetCallbackFns.add(fn),
         formStateRestoreCallback: (fn) => this.#formStateRestoreCallbackFns.add(fn),
+        customCallback: (fn) => {
+          const key = crypto.randomUUID();
+          this.__customCallbackFns.set(key, fn);
+          return `{{callback:${key}}}`;
+        },
         attrSignals: new Proxy(
           {},
           {
@@ -155,6 +162,9 @@ var customElement = (render, options) => {
     static get formAssociated() {
       return formAssociated;
     }
+    static get observedAttributes() {
+      return observedAttributes;
+    }
     constructor() {
       super();
       for (const attr of this.attributes) {
@@ -163,17 +173,28 @@ var customElement = (render, options) => {
       this.#render();
     }
     connectedCallback() {
-      this.#observer.observe(this, { attributes: true });
+      if (this.#observer !== null) {
+        this.#observer.observe(this, { attributes: true });
+      }
       for (const fn of this.#connectedFns) {
         fn();
       }
     }
     disconnectedCallback() {
-      this.#observer.disconnect();
+      if (this.#observer !== null) {
+        this.#observer.disconnect();
+      }
       for (const fn of this.#disconnectedFns) {
         fn();
       }
     }
+    attributeChangedCallback(name, oldValue, newValue) {
+      const [, setValue] = this.#attrSignals[name];
+      setValue(newValue);
+      for (const fn of this.#attributeChangedFns) {
+        fn(name, oldValue, newValue);
+      }
+    }
     adoptedCallback() {
       for (const fn of this.#adoptedCallbackFns) {
         fn();
@@ -245,6 +266,7 @@ var html = (strings, ...values) => {
     innerHTML += string + String(value);
   });
   const fragment = parseFragment(innerHTML);
+  const callbackBindingRegex = /(\{\{callback:.+\}\})/;
   const signalBindingRegex = /(\{\{signal:.+\}\})/;
   const parseChildren = (element) => {
     for (const child of element.childNodes) {
@@ -280,6 +302,9 @@ var html = (strings, ...values) => {
               }
               child.setAttribute(attr.name, newText);
             });
+          } else if (callbackBindingRegex.test(attr.value)) {
+            const uniqueKey = attr.value.replace(/\{\{callback:(.+)\}\}/, "$1");
+            child.setAttribute(attr.name, `this.getRootNode().host.__customCallbackFns.get('${uniqueKey}')(event)`);
           }
         }
         parseChildren(child);

package/dist/index.d.cts

@@ -22,15 +22,17 @@ type RenderProps = {
     formDisabledCallback: (fn: () => void) => void;
     formResetCallback: (fn: () => void) => void;
     formStateRestoreCallback: (fn: () => void) => void;
+    customCallback: (fn: () => void) => `{{callback:${string}}}`;
     attrSignals: Record<string, Signal<string | null>>;
     refs: Record<string, HTMLElement | null>;
     adoptStyleSheet: (stylesheet: CSSStyleSheet) => void;
 };
 type RenderOptions = {
-    formAssociated?: boolean;
+    formAssociated: boolean;
+    observedAttributes: string[];
 };
 type RenderFunction = (props: RenderProps) => DocumentFragment;
-declare const customElement: (render: RenderFunction, options?: RenderOptions) => ElementResult;
+declare const customElement: (render: RenderFunction, options?: Partial<RenderOptions>) => ElementResult;
 type Registry = {
     register: (tagName: string, element: CustomElementConstructor) => void;
     getTagName: (element: CustomElementConstructor) => string | undefined;

package/dist/index.d.ts

@@ -22,15 +22,17 @@ type RenderProps = {
     formDisabledCallback: (fn: () => void) => void;
     formResetCallback: (fn: () => void) => void;
     formStateRestoreCallback: (fn: () => void) => void;
+    customCallback: (fn: () => void) => `{{callback:${string}}}`;
     attrSignals: Record<string, Signal<string | null>>;
     refs: Record<string, HTMLElement | null>;
     adoptStyleSheet: (stylesheet: CSSStyleSheet) => void;
 };
 type RenderOptions = {
-    formAssociated?: boolean;
+    formAssociated: boolean;
+    observedAttributes: string[];
 };
 type RenderFunction = (props: RenderProps) => DocumentFragment;
-declare const customElement: (render: RenderFunction, options?: RenderOptions) => ElementResult;
+declare const customElement: (render: RenderFunction, options?: Partial<RenderOptions>) => ElementResult;
 type Registry = {
     register: (tagName: string, element: CustomElementConstructor) => void;
     getTagName: (element: CustomElementConstructor) => string | undefined;

package/dist/index.js

@@ -49,10 +49,11 @@ var createEffect = (fn) => {
 
 // src/custom-element.ts
 var DEFAULT_RENDER_OPTIONS = {
-  formAssociated: false
+  formAssociated: false,
+  observedAttributes: []
 };
 var customElement = (render, options) => {
-  const { formAssociated } = { ...DEFAULT_RENDER_OPTIONS, ...options };
+  const { formAssociated, observedAttributes } = { ...DEFAULT_RENDER_OPTIONS, ...options };
   class CustomElement extends HTMLElement {
     #attrSignals = {};
     #attributeChangedFns = /* @__PURE__ */ new Set();
@@ -62,9 +63,10 @@ var customElement = (render, options) => {
     #formDisabledCallbackFns = /* @__PURE__ */ new Set();
     #formResetCallbackFns = /* @__PURE__ */ new Set();
     #formStateRestoreCallbackFns = /* @__PURE__ */ new Set();
+    __customCallbackFns = /* @__PURE__ */ new Map();
     #shadowRoot = this.attachShadow({ mode: "closed" });
     #internals = this.attachInternals();
-    #observer = new MutationObserver((mutations) => {
+    #observer = observedAttributes.length > 0 ? null : new MutationObserver((mutations) => {
       for (const mutation of mutations) {
         const attrName = mutation.attributeName;
         if (mutation.type !== "attributes" || attrName === null) continue;
@@ -90,6 +92,11 @@ var customElement = (render, options) => {
         formDisabledCallback: (fn) => this.#formDisabledCallbackFns.add(fn),
         formResetCallback: (fn) => this.#formResetCallbackFns.add(fn),
         formStateRestoreCallback: (fn) => this.#formStateRestoreCallbackFns.add(fn),
+        customCallback: (fn) => {
+          const key = crypto.randomUUID();
+          this.__customCallbackFns.set(key, fn);
+          return `{{callback:${key}}}`;
+        },
         attrSignals: new Proxy(
           {},
           {
@@ -124,6 +131,9 @@ var customElement = (render, options) => {
     static get formAssociated() {
       return formAssociated;
     }
+    static get observedAttributes() {
+      return observedAttributes;
+    }
     constructor() {
       super();
       for (const attr of this.attributes) {
@@ -132,17 +142,28 @@ var customElement = (render, options) => {
       this.#render();
     }
     connectedCallback() {
-      this.#observer.observe(this, { attributes: true });
+      if (this.#observer !== null) {
+        this.#observer.observe(this, { attributes: true });
+      }
       for (const fn of this.#connectedFns) {
         fn();
       }
     }
     disconnectedCallback() {
-      this.#observer.disconnect();
+      if (this.#observer !== null) {
+        this.#observer.disconnect();
+      }
       for (const fn of this.#disconnectedFns) {
         fn();
       }
     }
+    attributeChangedCallback(name, oldValue, newValue) {
+      const [, setValue] = this.#attrSignals[name];
+      setValue(newValue);
+      for (const fn of this.#attributeChangedFns) {
+        fn(name, oldValue, newValue);
+      }
+    }
     adoptedCallback() {
       for (const fn of this.#adoptedCallbackFns) {
         fn();
@@ -214,6 +235,7 @@ var html = (strings, ...values) => {
     innerHTML += string + String(value);
   });
   const fragment = parseFragment(innerHTML);
+  const callbackBindingRegex = /(\{\{callback:.+\}\})/;
   const signalBindingRegex = /(\{\{signal:.+\}\})/;
   const parseChildren = (element) => {
     for (const child of element.childNodes) {
@@ -249,6 +271,9 @@ var html = (strings, ...values) => {
               }
               child.setAttribute(attr.name, newText);
             });
+          } else if (callbackBindingRegex.test(attr.value)) {
+            const uniqueKey = attr.value.replace(/\{\{callback:(.+)\}\}/, "$1");
+            child.setAttribute(attr.name, `this.getRootNode().host.__customCallbackFns.get('${uniqueKey}')(event)`);
           }
         }
         parseChildren(child);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "thunderous",
-	"version": "0.0.4",
+	"version": "0.2.0",
 	"description": "",
 	"type": "module",
 	"main": "./dist/index.cjs",