@a11d/lit 0.13.3 → 0.14.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.14.0 (2026-10-07)
+- **🚀 Feature**: Make hydration write the attributes the browser renders differently from the server ([58d6b39](https://github.com/a11delavar/lit/commit/58d6b397782bce86749001431dbc56b10a6cfce7))
+- **🚀 Feature**: Add `Component.hydrating`, true during a server-rendered component's first render in the browser ([58d6b39](https://github.com/a11delavar/lit/commit/58d6b397782bce86749001431dbc56b10a6cfce7))
+
+## 0.13.4 (2026-10-06)
+- **🧹 Chore**: Improve the package description and feature summaries ([285feac](https://github.com/a11delavar/lit/commit/285feac0f6a030647973e572344b168379227eb6))
+
 ## 0.13.3 (2026-09-28)
 - **🧹 Chore**: Ship the changelog and README with the package ([745c88f](https://github.com/a11delavar/lit/commit/745c88f9457ccbe3ad9ea927cbf2b48c3b106918))
 
@@ -96,4 +103,4 @@
 - **🧹 Chore**: Upgrade to Lit 3 ([f655b7f](https://github.com/a11delavar/lit/commit/f655b7ffcc83e69e06f4b336271093971fc35748))
 
 ## 0.4.0 (2023-10-10)
-- **🚀 Feature**: Add the nothing constant to the html template string literal function ([fea9a9b](https://github.com/a11delavar/lit/commit/fea9a9b6a7d9e220496b432b9f08589ae564af8b))
+- **🚀 Feature**: Add the nothing constant to the html template string literal function ([fea9a9b](https://github.com/a11delavar/lit/commit/fea9a9b6a7d9e220496b432b9f08589ae564af8b))

package/Component/README.md

@@ -1,12 +1,13 @@
 # `Component` class
 
-The `Component` class is the base class for all components.
+The base class for components, extending `LitElement` with a `template` getter and additional lifecycle callbacks.
 
 In addition to [Lit's standard lifecycle](https://lit.dev/docs/components/lifecycle/), `Component` provides:
 - `template` getter - Define the component's template
 - `initialized()` - Called once after the component is constructed
 - `connected()` - Called each time the component is connected to the DOM
 - `disconnected()` - Called each time the component is disconnected from the DOM
+- `hydrating` getter - Whether the first render in the browser must reproduce the server's
 
 ```ts
 import { component, Component, html, property } from '@a11d/lit'
@@ -35,4 +36,17 @@ class CustomButton extends Component {
 		`
 	}
 }
-```
+```
+
+## Server-side rendering
+
+A component rendered by [Lit SSR](https://lit.dev/docs/ssr/overview/) hydrates in the browser once `@lit-labs/ssr-client/lit-element-hydrate-support.js` is imported ahead of it. Hydration keeps the server's text and template choices, so the first render in the browser must give what the server gave, and the server saw no light DOM. `hydrating` is `true` during that render. Once it is done, the component updates once more, and every slot with content signals a `slotchange`, which the browser did not for server-rendered content. A template can therefore answer as the server did while hydrating and catch up right after:
+
+```ts
+protected override get template() {
+	const panes = isServer || this.hydrating ? [] : [...this.children]
+	return html`${panes.map(pane => html`<div part='pane'><slot name=${pane.slot}></slot></div>`)}`
+}
+```
+
+Attributes need no such care: Lit's hydration alone would keep the server's value of an attribute the browser renders differently, and `Component` makes it write those. This applies to every Lit template on a page that hydrates, not only to components, as it changes how Lit's attribute parts record their first value, and to no page that does not.

package/ComponentPart/README.md

@@ -1,6 +1,6 @@
 # `ComponentPart` class
 
-A `ComponentPart` is a part of a component, extracted into a class of its own **without introducing a component boundary**.
+A part of a component, extracted into a class of its own **without introducing a component boundary**.
 
 A part contributes a `template` to its host and may declare its own state, queries, events and event listeners with the very same decorators a component uses. As a part shares the update lifecycle of its host, changing the state of a part re-renders the host as a whole — no properties have to be passed down and no updates have to be propagated by hand.
 

package/Controller/README.md

@@ -1,6 +1,6 @@
 # `Controller` class
 
-A base class for [reactive controllers](https://lit.dev/docs/composition/controllers/) which registers itself with its host, so implementations only define the callbacks they are interested in.
+A base class for [reactive controllers](https://lit.dev/docs/composition/controllers/) that registers itself with its host. Implementations only define the callbacks they are interested in.
 
 ```ts
 import { Controller } from '@a11d/lit'

package/ElementRef/README.md

@@ -1,6 +1,6 @@
 # `ElementRef` / `ElementRefs` classes
 
-The element — or the elements — a template designates, with whatever it declares about them. Code gets the elements it works with from the template instead of querying for them.
+The element or elements a template designates, with whatever it declares about them. Code gets the elements it works with from the template instead of querying for them.
 
 ```ts
 import { Component, component, ElementRef, html } from '@a11d/lit'

package/README.md

@@ -13,10 +13,10 @@ npm install @a11d/lit
 <!-- features -->
 ## Features
 
-- **[`Component` class](https://github.com/a11delavar/lit/tree/main/packages/Lit/Component)** - The `Component` class is the base class for all components.
-- **[`ComponentPart` class](https://github.com/a11delavar/lit/tree/main/packages/Lit/ComponentPart)** - A `ComponentPart` is a part of a component, extracted into a class of its own **without introducing a component boundary**.
-- **[`Controller` class](https://github.com/a11delavar/lit/tree/main/packages/Lit/Controller)** - A base class for [reactive controllers](https://lit.dev/docs/composition/controllers/) which registers itself with its host, so implementations only define the callbacks they are interested in.
-- **[`ElementRef` / `ElementRefs` classes](https://github.com/a11delavar/lit/tree/main/packages/Lit/ElementRef)** - The element — or the elements — a template designates, with whatever it declares about them.
+- **[`Component` class](https://github.com/a11delavar/lit/tree/main/packages/Lit/Component)** - The base class for components, extending `LitElement` with a `template` getter and additional lifecycle callbacks.
+- **[`ComponentPart` class](https://github.com/a11delavar/lit/tree/main/packages/Lit/ComponentPart)** - A part of a component, extracted into a class of its own **without introducing a component boundary**.
+- **[`Controller` class](https://github.com/a11delavar/lit/tree/main/packages/Lit/Controller)** - A base class for [reactive controllers](https://lit.dev/docs/composition/controllers/) that registers itself with its host.
+- **[`ElementRef` / `ElementRefs` classes](https://github.com/a11delavar/lit/tree/main/packages/Lit/ElementRef)** - The element or elements a template designates, with whatever it declares about them.
 - **[`style` Directive](https://github.com/a11delavar/lit/tree/main/packages/Lit/style)** - Apply inline styles to elements with proper typing and reactivity.
 - **[`updated` Decorator](https://github.com/a11delavar/lit/tree/main/packages/Lit/updated)** - React to property changes with callbacks.
 - **[`eventListener` Decorator](https://github.com/a11delavar/lit/tree/main/packages/Lit/eventListener)** - Declaratively register event listeners on methods.
@@ -67,4 +67,4 @@ npm install @a11d/lit
 | `state` | const |  |
 | `ElementRefLifecycle` | interface | The lifecycle of the element or elements a reference holds. |
 | `BindSource` | type | The source a binding can be established on. |
-<!-- /exports -->
+<!-- /exports -->

package/bind/README.md

@@ -172,7 +172,7 @@ class MyParentComponent extends Component {
 
 ### Server-Side Rendering
 
-A server renders attribute, boolean attribute and property bindings with the source's value, but no element bindings, as Lit renders no element directives on a server. Hydration assumes an element's first render in the browser to equal the server's, so an element binding whose value changes what the element renders leaves it as the server rendered it. Server-rendered templates therefore bind the default property by name:
+A server renders attribute, boolean attribute and property bindings with the source's value, but no element bindings, as Lit renders no element directives on a server. In the browser, an element binding runs while the parent hydrates, before the element does, so the element's first render has the value the server's did not. That is fine as long as the value changes only the element's attributes, which hydration writes; where it changes text or a template choice, bind the default property by name, which the server renders too:
 
 ```ts
 html`<my-component .value=${bind(this, 'value')}></my-component>`

package/dist/Component/Component.d.ts

@@ -1,6 +1,14 @@
 import { LitElement, type PropertyValues } from 'lit';
+import './hydrateAttributes.js';
 export declare const component: (tagName: string) => import("lit/decorators.js").CustomElementDecorator;
 export declare abstract class Component extends LitElement {
+    private readonly hydration;
+    /**
+     * Whether the component renders its first update in the browser on top of the server's render, which it must reproduce,
+     * as hydration keeps the server's text and template choices and the server saw no light DOM.
+     * Another update follows at once, and every slot with content signals a `slotchange` then, which the browser did not.
+     */
+    get hydrating(): boolean;
     /** Invoked after first update i.e. render is completed */
     protected initialized(): void;
     /** Invoked every time the component is connected to the Document Object Model (DOM) */
@@ -11,6 +19,7 @@ export declare abstract class Component extends LitElement {
     protected get template(): import("lit-html").HTMLTemplateResult;
     /** @final */
     protected render(): import("lit-html").HTMLTemplateResult;
+    protected update(props: PropertyValues): void;
     /** @final */
     protected firstUpdated(props: PropertyValues): void;
     /** @final */

package/dist/Component/Component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Component.d.ts","sourceRoot":"","sources":["../../Component/Component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAA;AAIrD,eAAO,MAAM,SAAS,yEAAgB,CAAA;AAEtC,8BAAsB,SAAU,SAAQ,UAAU;IACjD,0DAA0D;IAC1D,SAAS,CAAC,WAAW;IAErB,uFAAuF;IACvF,SAAS,CAAC,SAAS;IAEnB,4FAA4F;IAC5F,SAAS,CAAC,YAAY;IAEtB,gGAAgG;IAChG,SAAS,KAAK,QAAQ,0CAErB;IAED,aAAa;cACM,MAAM;IAIzB,aAAa;cACM,YAAY,CAAC,KAAK,EAAE,cAAc;IAKrD,aAAa;IACJ,iBAAiB;IAK1B,aAAa;IACJ,oBAAoB;CAI7B"}
+{"version":3,"file":"Component.d.ts","sourceRoot":"","sources":["../../Component/Component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAA;AAIrD,OAAO,wBAAwB,CAAA;AAE/B,eAAO,MAAM,SAAS,yEAAgB,CAAA;AAEtC,8BAAsB,SAAU,SAAQ,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAEhD;;;;OAIG;IACH,IAAI,SAAS,YAEZ;IAED,0DAA0D;IAC1D,SAAS,CAAC,WAAW;IAErB,uFAAuF;IACvF,SAAS,CAAC,SAAS;IAEnB,4FAA4F;IAC5F,SAAS,CAAC,YAAY;IAEtB,gGAAgG;IAChG,SAAS,KAAK,QAAQ,0CAErB;IAED,aAAa;cACM,MAAM;cAIN,MAAM,CAAC,KAAK,EAAE,cAAc;IAK/C,aAAa;cACM,YAAY,CAAC,KAAK,EAAE,cAAc;IAKrD,aAAa;IACJ,iBAAiB;IAK1B,aAAa;IACJ,oBAAoB;CAI7B"}

package/dist/Component/Component.js

@@ -1,8 +1,22 @@
 import { LitElement } from 'lit';
 import { customElement } from 'lit/decorators.js';
 import { html } from './html.js';
+import { Hydration } from './Hydration.js';
+import './hydrateAttributes.js';
 export const component = customElement;
 export class Component extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.hydration = new Hydration(this);
+    }
+    /**
+     * Whether the component renders its first update in the browser on top of the server's render, which it must reproduce,
+     * as hydration keeps the server's text and template choices and the server saw no light DOM.
+     * Another update follows at once, and every slot with content signals a `slotchange` then, which the browser did not.
+     */
+    get hydrating() {
+        return this.hydration.hydrating;
+    }
     /** Invoked after first update i.e. render is completed */
     initialized() { }
     /** Invoked every time the component is connected to the Document Object Model (DOM) */
@@ -17,6 +31,10 @@ export class Component extends LitElement {
     render() {
         return this.template;
     }
+    update(props) {
+        super.update(props);
+        this.hydration.hostUpdate();
+    }
     /** @final */
     firstUpdated(props) {
         super.firstUpdated(props);

package/dist/Component/Hydration.d.ts

@@ -0,0 +1,16 @@
+import { type ReactiveControllerHost } from 'lit';
+/**
+ * Tracks the first update of a server-rendered host, which must give what the server gave, and lets it catch up right after:
+ * with another update, and a `slotchange` from every slot with content, which the browser signals only for content it assigned itself.
+ *
+ * The host drives it from `update()` rather than registering it as a controller, so that it acts before any controller of the host
+ * reads the light DOM in `hostUpdated`, and is not counted among the host's controllers.
+ */
+export declare class Hydration {
+    private readonly host;
+    hydrating: boolean;
+    constructor(host: ReactiveControllerHost & Element);
+    hostUpdate(): void;
+    private hydrated;
+}
+//# sourceMappingURL=Hydration.d.ts.map

package/dist/Component/Hydration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hydration.d.ts","sourceRoot":"","sources":["../../Component/Hydration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,sBAAsB,EAAE,MAAM,KAAK,CAAA;AAE3D;;;;;;GAMG;AACH,qBAAa,SAAS;IAGT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,SAAS,EAAE,OAAO,CAAA;gBAEW,IAAI,EAAE,sBAAsB,GAAG,OAAO;IAKnE,UAAU;IAOV,OAAO,CAAC,QAAQ;CAQhB"}

package/dist/Component/Hydration.js

@@ -0,0 +1,29 @@
+import { isServer } from 'lit';
+/**
+ * Tracks the first update of a server-rendered host, which must give what the server gave, and lets it catch up right after:
+ * with another update, and a `slotchange` from every slot with content, which the browser signals only for content it assigned itself.
+ *
+ * The host drives it from `update()` rather than registering it as a controller, so that it acts before any controller of the host
+ * reads the light DOM in `hostUpdated`, and is not counted among the host's controllers.
+ */
+export class Hydration {
+    constructor(host) {
+        this.host = host;
+        // A shadow root at construction is the server's, as Lit attaches one only on connection
+        this.hydrating = !isServer && !!host.shadowRoot;
+    }
+    hostUpdate() {
+        if (this.hydrating) {
+            this.hydrating = false;
+            this.host.updateComplete.then(() => this.hydrated());
+        }
+    }
+    hydrated() {
+        this.host.requestUpdate();
+        for (const slot of this.host.shadowRoot?.querySelectorAll('slot') ?? []) {
+            if (slot.assignedNodes().length > 0) {
+                slot.dispatchEvent(new Event('slotchange', { bubbles: true }));
+            }
+        }
+    }
+}

package/dist/Component/hydrateAttributes.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hydrateAttributes.d.ts.map

package/dist/Component/hydrateAttributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrateAttributes.d.ts","sourceRoot":"","sources":["../../Component/hydrateAttributes.ts"],"names":[],"mappings":""}

package/dist/Component/hydrateAttributes.js

@@ -0,0 +1,43 @@
+import { isServer, nothing } from 'lit';
+import { _$LH } from 'lit-html/private-ssr-support.js';
+// Lit's hydration support announces itself through this global ahead of any element, so a page which never hydrates is left alone
+if (!isServer && 'litElementHydrateSupport' in globalThis) {
+    const { AttributePart, BooleanAttributePart } = _$LH;
+    // Lit's production build mangles these two names to stable ones, by which its hydration package calls them as well
+    const setValueKey = ['_$setValue', '_$AI'].find(key => key in AttributePart.prototype);
+    if (!setValueKey) {
+        throw new Error('Hydration cannot write attributes, as this version of lit-html has renamed AttributePart.prototype._$setValue');
+    }
+    const committedValueKey = setValueKey === '_$setValue' ? '_$committedValue' : '_$AH';
+    const prototype = AttributePart.prototype;
+    const recorded = (part) => part[committedValueKey];
+    const setValue = prototype[setValueKey];
+    /** Writes the value as a render would, sparing the writes which would change nothing. */
+    const commit = (part, value) => {
+        const { element, name } = part;
+        if (part instanceof BooleanAttributePart) {
+            element.toggleAttribute(name, !!value && value !== nothing);
+        }
+        else if (value === nothing) {
+            element.removeAttribute(name);
+        }
+        else if (element.getAttribute(name) !== String(value ?? '')) {
+            element.setAttribute(name, String(value ?? ''));
+        }
+    };
+    prototype[setValueKey] = function (value, directiveParent, valueIndex, noCommit) {
+        if (noCommit !== true) {
+            return setValue.call(this, value, directiveParent, valueIndex, noCommit);
+        }
+        // Hydration passes "noCommit" to only record what a render would write. A render writes no initial "nothing", so the
+        // server's attribute stays, as it may be the element's own reflected default; an interpolation always records.
+        const { strings } = this;
+        const before = recorded(this);
+        setValue.call(this, value, directiveParent, valueIndex, noCommit);
+        const after = recorded(this);
+        if (strings || after !== before) {
+            const values = after;
+            commit(this, !strings ? after : values.includes(nothing) ? nothing : strings.reduce((text, string, i) => `${text}${values[i - 1] ?? ''}${string}`));
+        }
+    };
+}

package/dist/bind/Binder.d.ts

@@ -25,9 +25,9 @@ export declare class Binder<T> {
     constructor(host: BindSource, key: string);
     bind: (...[parameter]: BinderParameters<T>) => import("lit-html/directive.js").DirectiveResult<{
         new (partInfo: import("lit-html/directive.js").PartInfo): {
-            "__#private@#valueBinder"?: import("./ValueBinder.js").ValueBinder<import("lit-html").ElementPart | import("lit-html").AttributePart | import("lit-html").PropertyPart | import("lit-html").BooleanAttributePart>;
+            "__#private@#valueBinder"?: import("./ValueBinder.js").ValueBinder<import("lit-html").AttributePart | import("lit-html").BooleanAttributePart | import("lit-html").ElementPart | import("lit-html").PropertyPart>;
             render(component: BindSource, property: "requestUpdate", options?: BindDirectiveParametersOptions<(name?: PropertyKey, oldValue?: unknown, options?: import("lit").PropertyDeclaration, useNewValue?: boolean, newValue?: unknown) => void> | undefined): any;
-            update(part: import("lit-html").ElementPart | import("lit-html").AttributePart | import("lit-html").PropertyPart | import("lit-html").BooleanAttributePart, parameters: import("./BindDirective.js").BindDirectiveParameters<BindSource, "requestUpdate">): unknown;
+            update(part: import("lit-html").AttributePart | import("lit-html").BooleanAttributePart | import("lit-html").ElementPart | import("lit-html").PropertyPart, parameters: import("./BindDirective.js").BindDirectiveParameters<BindSource, "requestUpdate">): unknown;
             disconnected(): void;
             reconnected(): void;
             isConnected: boolean;

package/dist/bind/BindingIntegration.js

@@ -1,7 +1,7 @@
 export const bindingIntegrations = new Set();
 export const bindingIntegration = () => {
     return (BindingIntegrationConstructor) => {
-        bindingIntegrations.add(new BindingIntegrationConstructor);
+        bindingIntegrations.add(new BindingIntegrationConstructor());
     };
 };
 export class BindingIntegration {

package/dist/event/event.js

@@ -13,7 +13,7 @@ export function event(options) {
                 return this[`$${propertyKey}Event$`] ??= !isServer && element instanceof HTMLElement
                     ? new HTMLElementEventDispatcher(element, options?.type ?? propertyKey, options)
                     : new PureEventDispatcher();
-            }
+            },
         });
     };
 }

package/dist/eventListener/eventListener.js

@@ -29,7 +29,7 @@ export const eventListener = (...eventListenerOptions) => {
                             ? descriptor.get
                             : descriptor.value).call(context, event);
                 }
-            };
+            }();
         });
     };
 };

package/dist/query/query.js

@@ -4,7 +4,7 @@ export const query = (selector) => {
         Object.defineProperty(prototype, propertyKey, {
             get() {
                 return this[host]?.renderRoot?.querySelector(selector) ?? undefined;
-            }
+            },
         });
     };
 };

package/dist/query/queryAll.js

@@ -4,7 +4,7 @@ export const queryAll = (selector) => {
         Object.defineProperty(prototype, propertyKey, {
             get() {
                 return [...this[host]?.renderRoot?.querySelectorAll(selector) ?? []];
-            }
+            },
         });
     };
 };

package/dist/query/queryConnectedInstances.js

@@ -18,7 +18,7 @@ export function queryConnectedInstances() {
         Object.defineProperty(constructor, propertyName, { value: new Set() });
         constructor.addInitializer(element => element.addController({
             hostConnected: () => element.constructor[propertyName].add(element),
-            hostDisconnected: () => element.constructor[propertyName].delete(element)
+            hostDisconnected: () => element.constructor[propertyName].delete(element),
         }));
         Object.defineProperty(constructor, propertyKey, {
             configurable: false,

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@a11d/lit",
-	"version": "0.13.3",
-	"description": "A thin wrapper around the Lit library",
+	"version": "0.14.0",
+	"description": "A layer over Lit with a component base class, controllers, element references, two-way binding and typed events.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/a11delavar/lit.git",