Batch propchange events on a microtask drain

[DmitrySharabin]

Summary

propchange handlers were observing intermediate state during multi-prop synchronous writes. Microtask-batch dispatch so handlers always see settled state, plus a connected lifecycle hook that drains queued events on (re)connect.

Closes #51, closes #100.

Stacked on #108. Base auto-updates to main after #108 merges.

Why

class MyComponent extends NudeElement {
  static props = { color: {…}, space: {…} };

  propChangedCallback ({ name }) {
    // assumes both are in sync
    update(this.color, this.space);
  }
}

// caller:
el.color = newColor; // handler runs — new color, OLD space
el.space = newSpace; // handler runs — finally settled

Microtask coalescing collapses sync writes to one dispatch per prop with the settled value, and unifies timing across plain Signal and Computed-backed props.

API

Granularity	Event	Auto-wired callback
Per prop	propchange	propChangedCallback(event)
Per drain (bulk)	propschange	updated(event)

class MyElement extends NudeElement {
  static props = { foo: { /* … */ }, bar: { /* … */ } };

  propChangedCallback (event) {
    console.log(event.name, event.detail.value);
  }

  updated (event) {
    for (let [name, oldValue] of event.changedProps) {
      console.log(name, oldValue, "→", this[name]);
    }
  }
}

propschange fires once at the end of every drain, after every per-prop propchange. event.changedProps is Map<name, oldValue>; read the current value via this[name].

Implementation

• Coalescing — sync writes to the same prop collapse to one event per drain. Latest value / source win; oldValue and oldAttributeValue pin to the first write so the payload spans the full first→last delta.
• Round-trip filter — drain-time prop.equals skips coalesced no-ops (el.foo = X; el.foo = oldValue).
• Reflection is synchronous in Prop.set and #onComputedChange — not deferred to the drain.
• connected(element) drains the per-element dispatch queue on (re)connect (closes propchange events queued while disconnected are not dispatched on reconnect #100).
• updated() listener uses a stable method reference, so subclass re-attachment dedupes per the DOM spec.

Test plan

• npm test -- --ci — 99/100 PASS, 1 pre-existing skip, 0 FAIL

Follow-ups

• [Props] static props not inherited from parent class #104 — static props not inherited from a parent class. Latent; no consumer hits it today.
• setAttribute() after mount does not update the property on plain reflect props #98 — setAttribute after mount silently fails. Once fixed, the !isConnected guard in Props#attributeChanged comes out.

[netlify]

✅ Deploy Preview for nude-element ready!

Name	Link
🔨 Latest commit	7e07a9a
🔍 Latest deploy log	https://app.netlify.com/projects/nude-element/deploys/69fb4f0f5428b000084288be
😎 Deploy Preview	https://deploy-preview-102--nude-element.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[LeaVerou]

What if we keep propsChangedCallback() low-level like it is now and introduce a new updated() (and corresponding event) with the batched map?

[LeaVerou]

Haven't look at the code yet in detail, but on a high level,

Perhaps this is warranted, but at first glance, it feels disproportionate with the magnitude of the change which makes me worry that Claude may have overengineered this, as it often does.

The way I was thinking about it, we'd fire propchange as usual (sync, per property), but also have a debounced propschange (or propsupdate) that fires a certain delay after the last prop change (i.e. debounced).

This could live in the Props controller for a given element (perhaps make an ElementProps class instead of having method(element) on Props). It would listen to propchange, collect events, drain XXms after the last propchange OR wait until the element gets connected. For disconnected elements, I'd expect the low-level propchange to still fire, but not the higher level propschange. But that's not a strong opinion.

It seems that should be a fairly small and straightforward change, not ...whatever this is that Claude did. But perhaps I'm missing some factors that necessitated this complexity?

---

How does it behave with deep class hierarchies? Does updated() get fired with all props or just the class's own props? What behavior do we want? Would be useful to look at some of our own deep hierarchies and see what would be most useful.

---

console.log(name, payload.detail.oldInternalValue, "→", payload.detail.parsedValue);

Why do we need detail? What does payload give us by itself? Also, do we really need a whole object? Lit just does prop → old value. I can see how having both internal and parsed value can be useful. Do we need anything else? If not, I wonder if we should just have two simple maps. Or, we just provide the internal values, and people can always call parse() themselves. 🤔

---

For later: A lot of this seems useful for any class, the only part that's specific to custom elements is the attribute-property reflection. I wonder if at some point later we could extract the rest as a separate helper for reactive classes.

[DmitrySharabin]

Haven't look at the code yet in detail, but on a high level,

Perhaps this is warranted, but at first glance, it feels disproportionate with the magnitude of the change...

The real picture is not that bad, actually. The visible +824 is 67% tests and 7% README. The actual production-code change is +216 / −88 (net +128), and Prop.js inside that is a net −44 (reflection extraction is straight cleanup).

Initially, the actual driver of the PR wasn't #51; it was that propchange handlers observe intermediate states during multi-prop writes. For example,

class MyComponent extends NudeElement {
  static props = { color: {...}, space: {...} };
  propChangedCallback ({ name }) {
    // reads BOTH; assumes they're consistent
    update(this.color, this.space);
  }
}

// caller does:
el.color = newColor;  // handler runs — sees new color, OLD space
el.space = newSpace;  // handler runs — finally settled

Batching (and coalescing) is what fixes it. That's why it's also in this PR (and closes #51, but it's more of a consequence).

We also unify timing: today, plain Signal props fire propchange sync, Computed-backed props fire asynchronously (next microtask). With the PR, both fire on the drain. As a result, we have one consistent timing model.

How does it behave with deep class hierarchies? Does updated() get fired with all props or just the class's own props?

Based on the investigation, I filed an issue (#104).

Speaking of the changes in this PR, each class with static props gets its own Props instance with its own #eventDispatchQueue, #pendingElements, #drainScheduled. Independent drains, independent dispatches.

Why do we need detail? What does payload give us by itself? Also, do we really need a whole object? Lit just does prop → old value. I can see how having both internal and parsed value can be useful. Do we need anything else? If not, I wonder if we should just have two simple maps. Or, we just provide the internal values, and people can always call parse() themselves. 🤔

Agreed. A full bag is overkill. If we don't need all, I'd do it like Lit does. If a consumer needs source semantics or attribute round-trips, etc., that's what propChangedCallback already covers. Per-prop event shape stays as-is.

In the codebase, internal and parsed values are effectively the same thing. The signal stores the parsed/converted value; “internal” was just our naming for it. There's no separate raw form to expose. Tracking both was over-engineering.

If you like, I can split the PR into 2 or 3 separate ones. For example,

1. first_connected re-fire detail population fix (independent quality fix).
2. Settled-state coalescing + reconnect drain. Drops some over-engineered bits.
3. Bulk callback (updated/propsupdate).

Alternatively, we can have everything in one shot. 😅

[DmitrySharabin]

Real code changes are not that drastic, I suppose:

+152 / -62 (net +90)

[LeaVerou]

Initially, the actual driver of the PR wasn't #51; it was that propchange handlers observe intermediate states during multi-prop writes.

But that's exactly what #51 is about!

Agreed. A full bag is overkill. If we don't need all, I'd do it like Lit does. If a consumer needs source semantics or attribute round-trips, etc., that's what propChangedCallback already covers. Per-prop event shape stays as-is.

They do separate things though. I can see use cases where you might want all the info, but they're not the majority use case. But since we already have the detailed objects, it's also cheap to construct that map as well. So I'm leaning towards a signature like updated(simpleMap, mapWithAllTheDetails), then consumers with weird use cases can always use the second argument, but most consumers will be fine with the first.

OTOH we can always ship with the first argument only, and add the second if use cases come up that need it. Yes, let's do that actually. Simplicity first!

In the codebase, internal and parsed values are effectively the same thing. The signal stores the parsed/converted value; “internal” was just our naming for it. There's no separate raw form to expose. Tracking both was over-engineering.

I thought there were cases where we stored one value and the getter returned another but I could be misremembering.

If you like, I can split the PR into 2 or 3 separate ones. For example,

I think splitting 1 into a separate PR makes sense, if it's an independent fix. 2 and 3 seem more intertwined.

I still think propschange is a better event name than propsupdate. I can see the argument that it's only 1 character and can be mistyped, but the other one makes me wonder what the difference between change and update is.

Thanks re:subclasses. I agree we can tackle that separately.

[LeaVerou]

I don't understand this.

[DmitrySharabin]

The comment was opaque — fair. Updated in to lead with a “don't remove” warning and describe the timing concretely:

// Don't remove: re-fires initial propchange for on*= attribute handlers,
// which onprops attaches *after* the initial dispatch. Without this,
// shortcut handlers declared in HTML never see the initial event.
// Pre-connect imperative listeners receive the event twice.

Background: this re-fire was actually deleted in an earlier session, which broke <x-foo onfoochange="…"> handlers in color-elements. The previous comment was meant to deter future deletion but didn't communicate that clearly. Does this read better?

[LeaVerou]

Btw I think Claude didn't reply to this at all:

The way I was thinking about it, we'd fire propchange as usual (sync, per property), but also have a debounced propschange (or propsupdate) that fires a certain delay after the last prop change (i.e. debounced).

This could live in the Props controller for a given element (perhaps make an ElementProps class instead of having method(element) on Props). It would listen to propchange, collect events, drain XXms after the last propchange OR wait until the element gets connected. For disconnected elements, I'd expect the low-level propchange to still fire, but not the higher level propschange. But that's not a strong opinion.

It seems that should be a fairly small and straightforward change, not ...whatever this is that Claude did. But perhaps I'm missing some factors that necessitated this complexity?

It just justified its current solution (and I agree wrt the extent of changes). But I still want to know whether there's an error in my reasoning here.