@gluon/gluon 2.5.2 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to GluonJS are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [3.0.0] - 2026-10-09
+
+GluonJS 3 is a rewrite in TypeScript on lite-html. The lists below cover what changed for an element written against 2.x.
+
+### Added
+
+- Reactive properties, declared in the static `properties` map of an element. A declared property requests an update when it changes. With `attribute: true` it is set from the attribute with its kebab-cased name, and with `reflect: true` it is written back to that attribute. The `type` and `converter` options control the conversion, and `hasChanged` the change detection.
+- A batched update cycle. Changes are rendered once per microtask. `requestUpdate()`, `performUpdate()`, `updateComplete`, `isUpdatePending` and `hasUpdated` control and observe it, and the `shouldUpdate()`, `willUpdate()`, `update()`, `firstUpdated()` and `updated()` methods are called during it with the changed properties.
+- Static `styles`: CSS text, a constructed `CSSStyleSheet`, or a list of them, adopted by the shadow root of every instance. The `css` tag marks CSS in template literals.
+- `define(ElementClass, name, registry?)` registers an element class, and tolerates being called again with the same class.
+- `disconnectSignal`, an `AbortSignal` that is aborted when the element is disconnected, for listeners and observers set up in `connectedCallback()`.
+- Static `shadowRootOptions` for the shadow root that `createRenderRoot()` attaches.
+- Type declarations: the project is written in TypeScript and the package ships `.d.ts` files for the public API.
+
+### Changed
+
+- Templates are rendered with [lite-html](https://github.com/ruphin/lite-html) instead of lit-html. The `html`, `svg` and `render` functions and the directives of lite-html are exported from `@gluon/gluon`.
+- `render()` returns what the element renders, and is called by the update cycle. It replaces the `template` getter, and is no longer the method that schedules a render; use `requestUpdate()` and `performUpdate()` for that.
+- An element renders after it is connected and its first update completes, instead of synchronously in `connectedCallback()`.
+- The package entry point is the built ES module `dist/index.js`, which imports lite-html. The minified bundle `dist/gluon.min.js` includes lite-html and is what unpkg serves.
+
+### Removed
+
+- The `$` cache of nodes with an `id`. Query `renderRoot` instead.
+- `static get is()`. Pass the tag name to `define()` or `customElements.define()`.
+- `render({ sync: true })`. Call `performUpdate()` to update synchronously.
+- Rendering through lit-html's `shady-render`, for the ShadyDOM and ShadyCSS polyfills.
+
+## [2.5.3] - 2019-02-20
+
+Last release of the 2.x line, built on lit-html.
+
+[Unreleased]: https://github.com/ruphin/gluonjs/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/ruphin/gluonjs/compare/v2.5.3...v3.0.0
+[2.5.3]: https://github.com/ruphin/gluonjs/releases/tag/v2.5.3

package/README.md

@@ -1,220 +1,366 @@
-# Gluonjs
+# GluonJS
 
-[![Build Status](https://api.travis-ci.org/ruphin/gluonjs.svg?branch=master)](https://travis-ci.org/ruphin/gluonjs)
 [![NPM Latest version](https://img.shields.io/npm/v/@gluon/gluon.svg)](https://www.npmjs.com/package/@gluon/gluon)
-[![Code Style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 
-_A lightweight library for building web components and applications_
+_A tiny base class for Web Components_
 
 ---
 
-- **Platform Based:** GluonJS is designed to leverage the latest web platform capabilities, making it extremely small in size, and very performant on modern browsers. Additionally, it means that **build/compile steps are optional**; GluonJS components work on modern browsers without any pre-processing.
-- **Component Model:** Build components with encapsulated logic and style, then compose them to make complex interfaces. Uses the Web Component standards, with all related APIs available directly to developers.
-- **Highly Reusable:** Because GluonJS creates standards-compliant Web Components, you can use components created with GluonJS in almost any existing application. Check [Custom Elements Everywhere](https://custom-elements-everywhere.com/) for up-to-date compatibility tables with existing frameworks.
-- **Powerful Templating:** GluonJS uses [lit-html](https://github.com/PolymerLabs/lit-html) for templating, making it highly expressive and flexible.
+- **Reactive properties:** Declare the properties of an element once. Each one re-renders the element when it changes, and can be set from an attribute with type conversion and optional reflection.
+- **Batched rendering:** Templates are written with [lite-html](https://github.com/ruphin/lite-html) and rendered into a shadow root. Changes are batched into one render per microtask, and only the changed parts of the template are updated.
+- **Single file components:** Styles, properties, logic, and template live in one class, in one file. No decorators, no compiler settings, and no build step for plain JavaScript.
+- **Standards based:** Elements are plain custom elements, with the Web Component APIs available directly. They work in any framework, see [Custom Elements Everywhere](https://custom-elements-everywhere.com/).
 
-## Concepts
+## Example
 
-###
+```typescript
+import { GluonElement, define, html, css } from "@gluon/gluon";
 
-```javascript
-import { GluonElement } from '/node_modules/@gluon/gluon/gluon.js';
+class MyCounter extends GluonElement {
+  static override styles = css`
+    :host { display: inline-flex; gap: 8px; }
+    button { font: inherit; }
+  `;
 
-class MyElement extends GluonElement {
-  // ...
+  static override properties = {
+    count: { type: Number, attribute: true, reflect: true },
+    step: { type: Number, attribute: true },
+  };
+
+  count = 0;
+  step = 1;
+
+  override render() {
+    return html`
+      <button @click=${this.decrement}>-</button>
+      <span>${this.count}</span>
+      <button @click=${this.increment}>+</button>
+    `;
+  }
+
+  increment() {
+    this.count += this.step;
+    this.emit();
+  }
+
+  decrement() {
+    this.count -= this.step;
+    this.emit();
+  }
+
+  private emit() {
+    this.dispatchEvent(new CustomEvent("count-changed", { detail: { count: this.count }, bubbles: true, composed: true }));
+  }
 }
 
-customElements.define(MyElement.is, MyElement);
+define(MyCounter, "my-counter");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "my-counter": MyCounter;
+  }
+  interface GlobalEventHandlersEventMap {
+    "count-changed": CustomEvent<{ count: number }>;
+  }
+}
 ```
 
-### Rendering
+```html
+<script type="module" src="/my-counter.js"></script>
 
-Gluon uses [lit-html](https://github.com/PolymerLabs/lit-html) to efficiently render DOM into elements. The template to render is defined in the `template()` getter of an element, using JavaScript tagged template literals.
+<my-counter count="5" step="5"></my-counter>
+```
 
-If a `template` is defined, Gluon will render the template during the initialization of the element (when `super.connectedCallback()` is called).
+## Installing
 
-## API
+```
+npm install @gluon/gluon
+```
 
-### $
+GluonJS is published as an ES module with type declarations, and depends on `lite-html`. Import it from your bundler or import map:
 
-All nodes in the template with an `id` attribute are automatically mappped in the `$` property of an element. This provides an easy way to access named nodes without `querySelector` or `getElementById`.
+```javascript
+import { GluonElement, define, html, css } from "@gluon/gluon";
+```
 
-The map is created during the initial render of the template. Use `this.shadowRoot.getElementById()` to access nodes that are added after the initial render.
+Or load the bundle that includes lite-html:
 
-### static get is()
+```javascript
+import { GluonElement, define, html } from "https://unpkg.com/@gluon/gluon";
+```
 
-Returns a kebab-cased version of the element ClassName, as an easy default tagname for the customElementRegistry. This allows easy Custom Element registration using `customElements.define(MyElement.is, MyElement)`.
+The `html`, `svg`, and `render` functions and the directives of lite-html are exported from `@gluon/gluon` as well, so one import is enough.
 
-\*\* NOTE: JavaScript minifiers like es-uglify may break this feature. Use the `{ keep_fnames: true, mangle: {keep_fnames: true} }` options in es-uglify to avoid breaking this feature. Alternatively, override the method to return a string to define a fixed tagname: `
+## Elements
 
-‡ Pending IE support in [lit-html](https://github.com/PolymerLabs/lit-html)static get is() { return 'my-element' }`.
+An element is a class that extends `GluonElement`, registered with `define`:
 
-### get template()
+```typescript
+class MyElement extends GluonElement {
+  override render() {
+    return html`<p>Hello</p>`;
+  }
+}
 
-### render()
+define(MyElement, "my-element");
+```
 
-Calling `render()` on an element will queue a render at the next [microtask timing](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/). Multiple calls are automatically batched into a single render.
+### define(ElementClass, name, registry?)
 
-Returns a promise object that is fulfilled after the render is complete.
+Registers the class with a custom element registry under the tag name `name`, and returns the class.
 
-To render synchronously, `render({sync: true})`
+A name that is already registered is not registered again, so a module can be loaded more than once, for example by a development server that reloads modules. When the name is registered with a different class, the existing registration is kept and a warning is logged.
 
-## Common Patterns
+The `registry` defaults to the global `customElements`. Pass a scoped `CustomElementRegistry` to register the element in that scope.
 
-### Defining properties with getters and setters
+### render()
 
-This basic pattern works by defining a property getter and setter that wrap some other storage location for the property value.
+Returns what the element renders: a lite-html template, or any other [renderable value](https://github.com/ruphin/lite-html#renderable-values). The result is rendered into `renderRoot`, which is an open shadow root by default. Only the parts of the template that changed since the last render are updated.
 
-```javascript
-get someProp() {
-  return this._someProp;
-}
+Event handlers in the template are called with the element as `this`, so methods of the element can be used directly: `@click=${this.increment}`.
+
+`render()` runs in a microtask after the element is connected, and again after any of its properties change. It should be a pure function of the element's properties and state. Return `noChange` to leave the rendered content as it is.
+
+### createRenderRoot()
+
+Returns the node to render into. By default it attaches a shadow root with the static `shadowRootOptions`, or reuses the shadow root that already exists. Override it to render somewhere else:
 
-set someProp(value) {
-  this._someProp = value;
+```typescript
+class LightElement extends GluonElement {
+  protected override createRenderRoot() {
+    return this; // Render as the children of the element
+  }
 }
 ```
 
-Defining properties with getters and setters has no benefits in itself, but it makes for a more flexible system when adding more features such as property defaults, synchronising between properties and attributes, typed properties, or observing property changes, examples of which are listed below.
+The static `shadowRootOptions` default to `{ mode: "open" }`. Override them to make the shadow root closed, or to delegate focus:
 
-### Computed properties
+```typescript
+static override shadowRootOptions: ShadowRootInit = { mode: "open", delegatesFocus: true };
+```
 
-Computed properties can be created by defining a property getter that computes the value for the property.
+### styles
 
-```javascript
-get computedProp() {
-  return this.someProp + this.otherProp;
+The static `styles` are applied to the shadow root of every instance: a string of CSS, a constructed `CSSStyleSheet`, or an array of either. Each string is turned into one `CSSStyleSheet` that is shared by all instances. Where constructed stylesheets cannot be adopted, a `<style>` element is added to the shadow root instead.
+
+The `css` tag returns its template literal as a string. It marks the CSS for editors, formatters, and linters, and composes interpolated styles and numbers: `` css`${base} p { gap: ${8}px; }` ``.
+
+```typescript
+class StyledElement extends GluonElement {
+  static override styles = css`
+    :host { display: block; }
+    p { color: firebrick; }
+  `;
 }
 ```
 
-\*\* NOTE: Computed properties are re-computed for every reference to the property. When the computation is expensive, it may be worthwhile to implement a cache:
+Styles are not applied when the element renders into its light DOM. A class that is extended by another class with its own styles needs the `Styles` type annotation on the field, so TypeScript accepts a different value in the subclass:
 
-```javascript
-get computedProp() {
-  if (this.__previousSomeProp == this.someProp && this.__previousOtherProp === this.otherProp) {
-    return this.__cachedComputedProp;
-  }
+```typescript
+class BaseElement extends GluonElement {
+  static override styles: Styles = css`p { color: firebrick; }`;
+}
+
+class LoudElement extends BaseElement {
+  static override styles = [BaseElement.styles!, css`p { font-weight: bold; }`].flat();
 
-  this.__previousSomeProp = this.someProp;
-  this.__previousOtherProp = this.otherProp;
-  this.__cachedComputedProp = this.someProp + this.otherProp;
-  return this.__cachedComputedProp;
 }
 ```
 
-### Typed properties
+## Properties
 
-Define typed properties by adding type coercion in the property getter or setter.
-
-```javascript
-get numberProperty() {
-  return this._numberProperty;
-}
+Reactive properties are declared in the static `properties` map, and defined as class fields with their default values:
 
-set numberProperty(value) {
-  this._numberProperty = Number(value);
+```typescript
+class MyElement extends GluonElement {
+  static override properties = {
+    name: { attribute: true },
+    count: { type: Number, attribute: true, reflect: true },
+    active: { type: Boolean, attribute: true },
+    items: { type: Array },
+  };
+
+  name = "";
+  count = 0;
+  active = false;
+  items: string[] = [];
 }
 ```
 
-### Synchronising properties and attributes
+Every declared property becomes an accessor that requests an update when its value changes. The class field is the default value. A property has no attribute unless it is declared with `attribute: true`, which observes the kebab-cased name of the property: `maxValue` is set from `max-value`. The options of a property are:
 
-### Observing attribute changes
+| Option       | Default      | Meaning                                                                                                       |
+| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------- |
+| `type`       | `String`     | `String`, `Number`, `Boolean`, `Array`, or `Object`. A hint for the default converter                         |
+| `attribute`  | `false`      | Set the property from the attribute with its kebab-cased name                                                 |
+| `reflect`    | `false`      | Write the property to its attribute when it changes, including its initial value. Only with `attribute: true` |
+| `converter`  | built-in     | An object with `fromAttribute(value, type)` and `toAttribute(value, type)` functions                          |
+| `hasChanged` | `!Object.is` | A function `(value, oldValue) => boolean` that decides whether a new value counts as a change                 |
 
-Observing attribute changes is done using the Web Component attribute observer standards.
+The default converter copies `String` attributes, parses `Number` attributes with `Number()`, treats `Boolean` attributes as `true` when present, and parses `Array` and `Object` attributes as JSON. A property that is `null` or `undefined` removes its attribute when reflected. Rich data belongs in properties, not attributes: pass it from a template with `.items=${items}`, and leave `attribute` off.
 
-To observe changes on attributes, define a `static get observedAttributes()` on the class that returns an array of all attributes to observe:
+Changing a property requests an update. Mutating an array or object inside a property does not, because the property itself did not change. Either assign a new value, or call `requestUpdate()`:
 
-```javascript
-static get observedAttributes() {
-  return ['some-attr', 'other-attr']
+```typescript
+addItem(item: string) {
+  this.items = [...this.items, item]; // Requests an update
+}
+
+addItemInPlace(item: string) {
+  this.items.push(item);
+  this.requestUpdate(); // The element cannot see the push
 }
 ```
 
-With this defined, `attributeChangedCallback(attr, oldValue, newValue)` will be called for all attributes listed in the array.
+### Class fields and accessors
 
-```javascript
-attributeChangedCallback(attr, oldValue, newValue) {
-  if (attr === 'some-attr') {
-    // some-attr changed
-  } else if (attr === 'other-attr') {
-    // other-attr changed
-  }
-}
+A class field is defined on the instance when the element is constructed, and shadows the accessor on the prototype until the element is connected. At the first connect, the field is removed and its value is applied through the accessor. Properties and attributes that are set before that moment are kept, with one exception: a property that is set on an element before its class is defined is overwritten by the class field when the element is upgraded.
+
+To keep such values, declare the property with a getter and setter pair instead of a field. With TypeScript 5 or a bundler that lowers the keyword, the `accessor` keyword does the same in one line:
+
+```typescript
+accessor count = 0;
 ```
 
-\*\* NOTE: attributeChangedCallback is also called for the initial attributes set on an element. It is in fact called before the `connectedCallback()`, which means the template has not yet been rendered. If you need to interact with child nodes, use the promise returned by `render()` to guarantee the template has been rendered and the child nodes exist:
+Vite lowers `accessor` only with `experimentalDecorators: true` in `tsconfig.json`. Without that setting, the keyword reaches the browser unchanged, and no browser supports it yet.
 
-```javascript
-attributeChangedCallback(attr, oldValue, newValue) {
-  if (attr === 'some-attr') {
-    this.render().then( () => this.$.child.someFunction() );
-  }
+### A property with custom behaviour
+
+A declared property can have its own getter and setter. The setter is wrapped so it still requests an update:
+
+```typescript
+static override properties = { value: { type: Number } };
+
+#value = 0;
+
+get value() {
+  return this.#value;
+}
+
+set value(value: number) {
+  this.#value = Math.max(0, value);
 }
 ```
 
-### Observing property changes
+### Inheritance
 
-Observing property changes is done by calling the observer at the end of the property setter function.
+A class inherits the properties of its superclass, and can declare more. A class that is extended by another class with its own properties needs the `PropertyDeclarations` type annotation on the map, so TypeScript accepts a different map in the subclass:
 
-```javascript
-get someProp() {
-  return this._someProp;
+```typescript
+class BaseElement extends GluonElement {
+  static override properties: PropertyDeclarations = { name: { attribute: true } };
+  name = "";
 }
 
-set someProp(value) {
-  this._someProp = value;
-  this.somePropChanged();
+
+class ExtendedElement extends BaseElement {
+  static override properties = { count: { type: Number } };
+  count = 0;
 }
 ```
 
-## Examples
+## Updates
 
-Here is an example of a GluonJS component:
+Changing a property schedules an update in a microtask. All changes before the microtask are batched into one update. An update runs these methods in order, each with a `PropertyValues` map of the changed properties to their previous values:
 
-```javascript
-// helloMessage.js
-import { GluonElement, html } from '/node_modules/@gluon/gluon/gluon.js';
+1. `shouldUpdate(changed)`: return `false` to skip the update. Defaults to `true`.
+2. `willUpdate(changed)`: compute values that depend on the changed properties, before rendering.
+3. `update(changed)`: reflects properties to attributes, and renders `render()` into `renderRoot`. Call `super.update(changed)` when overriding it.
+4. `firstUpdated(changed)`: called once, after the first update. The rendered DOM exists from here on.
+5. `updated(changed)`: called after every update.
 
-class HelloMessage extends GluonElement {
-  get template() {
-    return html`<div>Hello ${this.getAttribute('name')}</div>`;
+```typescript
+class FullName extends GluonElement {
+  static override properties = { first: {}, last: {} };
+  first = "";
+  last = "";
+  full = "";
+
+  override willUpdate(changed: PropertyValues<this>) {
+    if (changed.has("first") || changed.has("last")) {
+      this.full = `${this.first} ${this.last}`;
+    }
+  }
+
+  override render() {
+    return html`<p>${this.full}</p>`;
   }
 }
+```
+
+The first update waits for the element to be connected. Elements render after they are connected, whether or not they are still connected.
 
-customElements.define(HelloMessage.is, HelloMessage);
+### updateComplete
+
+A promise that resolves when the pending update completes. It resolves with `true` when no further update was requested during the update, and `false` otherwise. Await it before reading the rendered DOM:
+
+```typescript
+element.count = 5;
+await element.updateComplete;
+element.renderRoot.querySelector("span"); // Shows 5
 ```
 
-We can import and use this component from anywhere:
+### requestUpdate(name?, oldValue?)
 
-```html
-<!-- index.html -->
-<script type="module" src="/helloMessage.js"></script>
+Requests an update. Call it without arguments after a change the element cannot see, such as a mutation of an array in a property. The setters of declared properties call it with the property name and its previous value.
+
+### performUpdate()
+
+Performs the pending update now, instead of in a microtask.
+
+### isUpdatePending and hasUpdated
+
+`isUpdatePending` is `true` while an update is scheduled. `hasUpdated` is `true` after the first update.
+
+## Lifecycle
 
-<hello-message name="World"></hello-message>
+The standard custom element callbacks are available. Call the `super` method when overriding `connectedCallback()`, `disconnectedCallback()`, or `attributeChangedCallback()`.
+
+`connectedCallback()` runs every time the element is connected, including when it is moved. Listeners on the document or window belong here, with the `disconnectSignal` as their `signal`, so they are removed when the element is disconnected:
+
+```typescript
+override connectedCallback() {
+  super.connectedCallback();
+  window.addEventListener("resize", this.measure, { signal: this.disconnectSignal });
+}
 ```
 
-This example will render "Hello World".
+`disconnectSignal` is an `AbortSignal` that is aborted when the element is disconnected. A new signal is created on every connect.
 
-## Installation
+## Events
 
-GluonJS is available through [npm](https://www.npmjs.com) as `@gluon/gluon`.
+Dispatch events with `dispatchEvent`. An event that should be heard outside the shadow root needs `composed: true`, and `bubbles: true` to reach ancestors:
 
-## Compatibility
+```typescript
+this.dispatchEvent(new CustomEvent("count-changed", { detail: { count: this.count }, bubbles: true, composed: true }));
+```
 
-| Chrome | Safari | Firefox | Edge | IE   |
-| ------ | ------ | ------- | ---- | ---- |
-| ✔      | ✔      | \*      | \*   | \* † |
+Declare the event in `GlobalEventHandlersEventMap`, so `addEventListener("count-changed", ...)` is typed on elements, documents, and windows:
 
-\* Requires [Web Component polyfill](https://www.webcomponents.org/polyfills/)
+```typescript
+declare global {
+  interface GlobalEventHandlersEventMap {
+    "count-changed": CustomEvent<{ count: number }>;
+  }
+}
+```
+
+## TypeScript
 
-† Requires transpiling to ES5
+GluonJS ships type declarations and needs no compiler settings. Declare every element in `HTMLElementTagNameMap`, so `document.createElement("my-counter")` and `querySelector("my-counter")` return the element class:
 
-## Contributing
+```typescript
+declare global {
+  interface HTMLElementTagNameMap {
+    "my-counter": MyCounter;
+  }
+}
+```
 
-All work on GluonJS happens in the open on [Github](https://github.com/ruphin/gluonjs). A development environment is available at `localhost:5000` with `npm install && npm run dev`, or `make dev` if you use [Docker](https://www.docker.com/). All issue reports and pull requests are welcome.
+With `noImplicitOverride`, the overridden members of the base class carry the `override` keyword, as in the examples above. Without it, the keyword can be left out.
 
 ## License
 
-[MIT](http://opensource.org/licenses/MIT)
+[MIT](https://opensource.org/licenses/MIT)
 
-Copyright © 2017-present, Goffert van Gool
+Copyright © 2026-present, Goffert van Gool