thunderous 0.0.4 → 0.1.0

package/README.md

@@ -35,20 +35,16 @@ const myStyleSheet = css`
 `;
 
 const MyElement = customElement((params) => {
-  const { connectedCallback, refs, adoptStyleSheet } = params;
+  const { customCallback, refs, adoptStyleSheet } = params;
 
   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>
   `;
 });
@@ -157,19 +153,15 @@ Creating signals should look pretty familiar to most modern developers.
 
 <!-- prettier-ignore-start -->
 ```ts
-import { createSignal, customElement } from 'thunderous';
-
-const MyElement = customElement(() => {
-  const [count, setCount] = createSignal(0);
+import { createSignal } from 'thunderous';
 
-  console.log(count()); // 0
+const [count, setCount] = createSignal(0);
 
-  setCount(1);
+console.log(count()); // 0
 
-  console.log(count()) // 1
+setCount(1);
 
-  /* ... */
-});
+console.log(count()) // 1
 ```
 <!-- prettier-ignore-end -->
 
@@ -223,33 +215,79 @@ Usage:
 
 > NOTICE: Since `attrSignals` is a `Proxy` object, _any_ property will return a signal and auto-bind it to the attribute it corresponds with.
 
+##### Derived Signals
+
+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.
+
+```ts
+import { derived, createSignal } from 'thunderous';
+
+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
 
-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.
+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((params) => {
   const { connectedCallback, refs } = params;
 
-  const [count, setCount] = createSignal(0);
-
   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((params) => {
+  const { customCallback } = params;
+
+  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

@@ -93,6 +93,7 @@ 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) => {
@@ -121,6 +122,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(
           {},
           {
@@ -245,6 +251,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 +287,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,6 +22,7 @@ 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;

package/dist/index.d.ts

@@ -22,6 +22,7 @@ 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;

package/dist/index.js

@@ -62,6 +62,7 @@ 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) => {
@@ -90,6 +91,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(
           {},
           {
@@ -214,6 +220,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 +256,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.1.0",
 	"description": "",
 	"type": "module",
 	"main": "./dist/index.cjs",