thunderous 0.3.0 → 0.3.1

package/README.md

@@ -8,6 +8,7 @@ Each component renders only once, then binds signals to DOM nodes for direct upd
 
 - [Installation](#installation)
 - [Usage](#usage)
+- [Documentation](#documentation)
 - [Development](#development)
 - [License](#license)
 
@@ -48,347 +49,9 @@ MyElement.define('my-element');
 ```
 <!-- prettier-ignore-end -->
 
-### The Native Features
+## Documentation
 
-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 instead.
-
-<!-- prettier-ignore-start -->
-```ts
-const MyElement = customElement((params) => {
-  const {
-    adoptedCallback,
-    connectedCallback,
-    disconnectedCallback,
-    attributeChangedCallback,
-  } = params;
-  /* ... */
-});
-```
-<!-- prettier-ignore-end -->
-
-If you need to support forms, pass an options object as the second argument to `customElement`.
-
-<!-- prettier-ignore-start -->
-```ts
-const MyElement = customElement((params) => {
-  const {
-    formDisabledCallback,
-    formResetCallback,
-    formStateRestoreCallback,
-  } = params;
-  /* ... */
-}, { 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.
-
-<!-- prettier-ignore-start -->
-```ts
-const MyElement = customElement((params) => {
-  const {
-    internals,
-    elementRef,
-    root,
-    connectedCallback,
-  } = params;
-
-  internals.setFormValue('hello world');
-  connectedCallback(() => {
-    const childLink = elementRef.querySelector('a[href]'); // light DOM
-    const innerLink = root.querySelector('a[href]'); // shadow DOM
-    /* ... */
-  });
-  /* ... */
-}, { formAssociated: true });
-```
-<!-- prettier-ignore-end -->
-
-If you need to pass certain options to the `attachShadow()` call, you can do so by passing `shadowRootOptions`.
-
-<!-- prettier-ignore-start -->
-```ts
-const MyElement = customElement(() => {
-  /* ... */
-}, { shadowRootOptions: { delegatesFocus: true } });
-```
-<!-- prettier-ignore-end -->
-
-To opt out of using shadow DOM at all, pass `false` to `attachShadow`. This will change `root` above to reference the element itself, and stylesheets will apply to the global document rather than being encapsulated within the component.
-
-<!-- prettier-ignore-start -->
-```ts
-const MyElement = customElement(() => {
-  /* ... */
-}, { attachShadow: false });
-```
-<!-- prettier-ignore-end -->
-
-#### Adopted Style Sheets
-
-This one diverges from native slightly, since the native approach is a bit manual. For convenience, you can use the `adoptStyleSheet()` function.
-
-> If you prefer the manual approach, `root.adoptedStyleSheets = []`, you can always do that with the `root` property above, or the global `document`.
-
-The `css` tagged template function will construct a `CSSStyleSheet` object that can be adopted by documents and shadow roots.
-
-> When `attachShadow` is set to `false`, `adoptStyleSheet()` will use the global document to adopt the styles.
-
-<!-- prettier-ignore-start -->
-```ts
-import { customElement, css } from 'thunderous';
-
-const myStyleSheet = css`
-  :host {
-    display: block;
-    font-family: sans-serif;
-  }
-`;
-
-const MyElement = customElement(({ adoptStyleSheet }) => {
-  adoptStyleSheet(myStyleSheet);
-  /* ... */
-});
-```
-<!-- prettier-ignore-end -->
-
-### Non-Native extras
-
-In addition to the native features, there are a few features that supercharge your web components. Most notably, signals.
-
-#### Signals
-
-Creating signals should look pretty familiar to most modern developers.
-
-<!-- prettier-ignore-start -->
-```ts
-import { createSignal } from 'thunderous';
-
-const [count, setCount] = createSignal(0);
-console.log(count()); // 0
-setCount(1);
-console.log(count()) // 1
-```
-<!-- prettier-ignore-end -->
-
-##### Binding Signals to Templates
-
-To bind signals to a template, use the provided `html` tagged template function to pass them in.
-
-<!-- prettier-ignore-start -->
-```ts
-import { createSignal, customElement, html } from 'thunderous';
-
-const MyElement = customElement(() => {
-  const [count, setCount] = createSignal(0);
-  // presumably setCount() gets called
-  return html`<output>${count}</output>`;
-});
-```
-<!-- prettier-ignore-end -->
-
-> NOTICE: we are not running the signal's getter above. This is intentional, as we delegate that to the template to run for proper binding.
-
-By binding signals to templates, you allow fine-grained updates to be made directly to DOM nodes every time the signal changes, without requiring any diffing or re-rendering.
-
-> This also works for `css`, but bear in mind that passing signals to a shared `CSSStyleSheet` may not have the effect you expect. Sharing Style Sheets across many component instances is best for performance, but signals will update every instance of each component with that approach. The suggested alternative is to write static CSS and toggle classes in the HTML instead.
-
-##### Attribute Signals
-
-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(({ attrSignals }) => {
-  const [heading, setHeading] = attrSignals['my-heading'];
-  // setHeading() will also update the attribute in the HTML.
-  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
-<my-element my-heading="My Element's Title"></my-element>
-```
-
-> NOTICE: Since `attrSignals` is a `Proxy` object, _any_ property will return a signal and auto-bind it to the attribute it corresponds with.
-
-##### Property Signals
-
-In addition to attributes, there are also properties. Though often conflated, there is an important distinction: _attributes_ are strings defined in HTML, and _properties_ can be any type of data, strictly in JavaScript and completely invisible to HTML.
-
-Modern templating solutions often allow developers to assign properties via HTML attribute _syntax_, even though they are not actually attributes. While this distinction may seem trivial for those working with modern frameworks, it becomes much more relevant when defining custom elements that may be used in plain HTML.
-
-Thunderous supports properties for cases where strings are not sufficient. These are also reflected as signals _within_ the component, but the _consumer_ of the component will not directly interact with this signal. `myElement.count = 1` will update the internal signal.
-
-<!-- prettier-ignore-start -->
-```ts
-const MyElement = customElement(({ propSignals }) => {
-  const [count, setCount] = propSignals['prop'];
-  // setCount() will also update the property in the DOM
-  return html`<output>${count}</output>`;
-});
-```
-<!-- prettier-ignore-end -->
-
-There is also a way to sync attributes with properties, though it should be used deliberately, with caution. Since it requires some coercion to occur, it may introduce some performance overhead. It's best not to use this to parse JSON strings, for example.
-
-To use this feature, pass `attributesAsProperties` in the options. It accepts an array of `[propertyName, coerceFn]` pairs. For primitive types, you can use their constructors for coercion, like `['count', Number]`.
-
-<!-- prettier-ignore-start -->
-```ts
-const MyElement = customElement(({ propSignals }) => {
-  const [count, setCount] = propSignals['prop'];
-  // setCount() will also update the property in the DOM
-  return html`<output>${count}</output>`;
-}, { attributesAsProperties: [['count', Number]] });
-```
-<!-- prettier-ignore-end -->
-
-With the above snippet, `count` may be controlled by setting the attribute, like so:
-
-```html
-<my-element count="1"></my-element>
-```
-
-...and the attribute will reflect changes made to the property as well:
-
-```ts
-const myElement = document.querySelector('my-element');
-myElement.count = 1;
-```
-
-In both cases, the `count()` signal will be updated.
-
-##### 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());
-});
-```
-
-##### Debugging Signals
-
-If you're having a tough time tracing an issue, you can provide the `debugMode` option to any signal to log potentially helpful information to the console. For differentiating values, you can also provide an optional `label` property to easily associate logs with their respective sources. These options can be passed to signals themselves, or to specific calls to setters and getters.
-
-```ts
-const [count, setCount] = createSignal(0, {
-  debugMode: true,
-  label: 'count signal',
-});
-
-setCount(1, {
-  debugMode: true,
-  label: 'start count',
-});
-
-const newCount = count({
-  debugMode: true,
-  label: 'new 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(() => {
-    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 onclick="${increment}">Increment</button>
-    <output>${count}</output>
-  `;
-});
-```
-
-> NOTICE: This uses the native HTML inline event-binding syntax. There is no special syntax for `on` attributes, because it simply renders the reference to the host element.
->
-> You will see something like this when you inspect the element in the browser:
-> ```html
-> <my-element onclick="this.getRootNode().host.__customCallbackFns.get('d7121610-e89d-4629-ab00-d4e22644f16b')(event)">
-> ```
-<!-- prettier-ignore-end -->
-
-### 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()`.
+Please consult the [documentation](https://thunderous.dev) to learn how to build web components with Thunderous.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "thunderous",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -43,7 +43,7 @@
 		"eslint-plugin-promise": "^7.1.0",
 		"express": "^4.17.1",
 		"prettier": "^3.3.3",
-		"typescript": "^5.6.3",
-		"tsup": "^8.3.0"
+		"tsup": "^8.3.0",
+		"typescript": "^5.6.3"
 	}
 }