@a11d/lit 0.13.4 → 0.14.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.14.1 (2026-10-07)
+- **🐛 Fix**: Run `@property({ updated })` hooks with Lit's hydration support loaded ([52b35bc](https://github.com/a11delavar/lit/commit/52b35bc93974f87e7e5e3237e86dd51a0a75df63))
+
+## 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))
 

package/Component/README.md

@@ -7,6 +7,7 @@ In addition to [Lit's standard lifecycle](https://lit.dev/docs/components/lifecy
 - `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/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/updated/UpdatedController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UpdatedController.d.ts","sourceRoot":"","sources":["../../updated/UpdatedController.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAQ,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAepD,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAA;AAEhE,qBAAa,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC,CAAE,SAAQ,UAAU;IAG/E,QAAQ,CAAC,OAAO,EAAE,CAAC;IAAE,QAAQ,CAAC,WAAW,EAAE,CAAC;IAAE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAFlG,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAa;gBAE3B,OAAO,EAAE,CAAC,EAAW,WAAW,EAAE,CAAC,EAAW,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAKlG,OAAO,KAAK,KAAK,GAA4C;IAEpD,WAAW;CAMpB"}
+{"version":3,"file":"UpdatedController.d.ts","sourceRoot":"","sources":["../../updated/UpdatedController.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAQ,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAqBpD,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAA;AAEhE,qBAAa,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC,CAAE,SAAQ,UAAU;IAG/E,QAAQ,CAAC,OAAO,EAAE,CAAC;IAAE,QAAQ,CAAC,WAAW,EAAE,CAAC;IAAE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAFlG,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAa;gBAE3B,OAAO,EAAE,CAAC,EAAW,WAAW,EAAE,CAAC,EAAW,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAKlG,OAAO,KAAK,KAAK,GAA4C;IAEpD,WAAW;CAMpB"}

package/dist/updated/UpdatedController.js

@@ -1,13 +1,18 @@
-import { ReactiveElement } from 'lit';
+import { LitElement, ReactiveElement } from 'lit';
 import { Controller } from '../Controller/index.js';
 import { host } from '../host.js';
 import { getChangedPropertyKey } from './getChangedPropertyKey.js';
 const changedPropertiesKey = Symbol('changedProperties');
-const originalUpdate = ReactiveElement.prototype['update'];
-ReactiveElement.prototype['update'] = function (changedProperties) {
-    this[changedPropertiesKey] = changedProperties;
-    return originalUpdate.call(this, changedProperties);
+const recordChangedProperties = (prototype) => {
+    const update = prototype['update'];
+    prototype['update'] = function (changedProperties) {
+        this[changedPropertiesKey] = changedProperties;
+        return update.call(this, changedProperties);
+    };
 };
+recordChangedProperties(ReactiveElement.prototype);
+// Lit's hydration support replaces LitElement's update with one calling the ReactiveElement update it captured before this module ran
+recordChangedProperties(LitElement.prototype);
 export class UpdatedController extends Controller {
     constructor(context, propertyKey, callback) {
         super(context[host]);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@a11d/lit",
-	"version": "0.13.4",
+	"version": "0.14.1",
 	"description": "A layer over Lit with a component base class, controllers, element references, two-way binding and typed events.",
 	"repository": {
 		"type": "git",