thunderous 0.0.3 → 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>
   `;
 });
@@ -59,35 +55,11 @@ MyElement.define('my-element');
 
 ### The Native Features
 
-Everything the native class definition can do, this can do too. You'll find that these things are not far removed from the native approach, so they ought to be familiar.
-
-#### Defining Custom Elements
-
-The `customElement` function allows you to author the web component with the render function and it returns an `ElementResult` that has some helpful methods like `define()` and `eject()`.
-
-- `ElementResult.define()` is a little safer than `customElements.define()` because it first checks if the component was already defined, without throwing an error. It will, however, log a warning. There's no need to pass the class since it already has that context.
-
-  ```ts
-  const MyElement = customElement(() => html`<slot></slot>`);
-
-  MyElement.define('my-element');
-  ```
-
-- `ElementResult.eject()` is useful in case you need to access the underlying class for some reason; perhaps you want to extend it and/or set static properties.
-
-  ```ts
-  const MyElementClass = MyElement.eject();
-
-  class MyOtherElement extends MyElementClass {
-    /* ... */
-  }
-  ```
-
-These may also be chained together, like `MyElement.define('my-element').eject()`.
+Everything the native class definition can do, this function can do too. You'll find that these things are not far removed from the native approach, so they ought to be familiar.
 
 #### Lifecycle Methods
 
-Any lifecycle method you may need can be accessed from the params of your render function. The only difference is that these are callback registrations, so the same callback you would normally write is just passed in.
+Any lifecycle method you may need can be accessed from the params of your render function. The only difference is that these are callback registrations, so the same callback you would normally write is just passed in instead.
 
 <!-- prettier-ignore-start -->
 ```ts
@@ -120,24 +92,6 @@ const MyElement = customElement((params) => {
 ```
 <!-- prettier-ignore-end -->
 
-#### Element Internals
-
-You can always define the internals the same as you usually would.
-
-<!-- prettier-ignore-start -->
-```ts
-const MyElement = customElement((params) => {
-  const {
-    internals,
-  } = params;
-
-  internals.ariaRequired = 'true';
-
-  /* ... */
-}, { formAssociated: true });
-```
-<!-- prettier-ignore-end -->
-
 #### Roots and Element Internals
 
 You can always define the internals the same as you usually would, and if for some reason you need access to either the element itself or the shadow root, you can do so as illustrated below.
@@ -199,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 -->
 
@@ -265,33 +215,103 @@ 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()`.
+
+- `ElementResult.define()` is a little safer than `customElements.define()` because it first checks if the component was already defined, without throwing an error. It will, however, log a warning. There's no need to pass the class since it already has that context.
+
+  ```ts
+  const MyElement = customElement(() => html`<slot></slot>`);
+
+  MyElement.define('my-element');
+  ```
+
+- `ElementResult.eject()` is useful in case you need to access the underlying class for some reason; perhaps you want to extend it and/or set static properties.
+
+  ```ts
+  const MyElementClass = MyElement.eject();
+
+  class MyOtherElement extends MyElementClass {
+    /* ... */
+  }
+  ```
+
+These may also be chained together, like `MyElement.define('my-element').eject()`.
+
 ## Contributing
 
 ### Local Server

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.3",
+	"version": "0.1.0",
 	"description": "",
 	"type": "module",
 	"main": "./dist/index.cjs",