Add batched propschange event

[LeaVerou]

Summary

Adds a new propschange event: a coalesced, microtask-deferred batch event that fires once after a burst of propchange events settles, carrying the net first→last delta per prop as Map<name, oldValue>. Round-trips (value returns to its burst-start) drop out. Lives in a new propschange sub-plugin under props/ and is auto-wired to subclasses that define an updated(event) method, mirroring Lit's updated(changedProperties).

Mount fires one propschange with every prop in changed (oldValue: undefined), so initial values arrive as a single settled snapshot.

Compared to main

New: propschange event + plugin (src/plugins/props/propschange.js)

Listens for propchange on each instance, maintains per-prop burst tracking (firstOldValue + latest value + spec), and fires one PropsChangeEvent("propschange", { changed }) per microtask. Auto-wires updated(event). The props/ plugin folder now mirrors the events/ pattern: base.js is the core props plugin, index.js is a meta-plugin bundling base + propschange, so the default NudeElement ships with both. Anyone who wants props core in isolation can import props/base.js.

New: ElementProp.source

Tracks where the current value came from: "default" | "property" | "attribute" | "get" | "convert". Drives the "user-owned" stickiness ElementProps uses to keep a "get" recompute from silently stripping ownership that a prior property/attribute write established.

Breaking: PropChangeEvent shape

PropChangeEvent now extends Event (not CustomEvent) and exposes its fields directly — e.value, e.oldValue, e.source, e.attributeName, etc. — instead of nesting under e.detail. Each dispatch gets a fresh event object; fields don't mutate past the handler.

Downstream impact (incl. color-elements): e.detail.* → e.* on propchange listeners.

Behavior: paused/resume sequential coalescing

paused/resume themselves already existed on main, but on paused = false the queue used to flush every queued event verbatim. Now it walks the queue in write order and in-place coalesces consecutive same-prop entries (preserving the run's burst-start oldValue), dispatching one event per run. A sequence like A A B A produces three dispatches, not two — non-adjacent same-prop runs stay separate, so the consumer hears a faithful narrative.

Behavior: on*= handlers in markup

On*-prop handlers now attach via the on* prop's spec changed callback, which runs synchronously inside ElementProp.changed — before propChanged fires. Handlers bind during the prop's own init pass, in time for the mount propchanges that follow. Markup <x onfoo="…"> receives the mount-time event with its real source (e.g. "default") rather than a synthesized "initial" re-fire.

Tests

• npx htest test/index.js — 185/189 pass (4 pre-existing skips)
• Update color-elements for the e.detail → e.* flat-shape change and sanity-check the propschange / source-state behavior

[netlify]

✅ Deploy Preview for nude-element ready!

Name	Link
🔨 Latest commit	caf6f2c
🔍 Latest deploy log	https://app.netlify.com/projects/nude-element/deploys/6a1da4cc1415e9000891a95b
😎 Deploy Preview	https://deploy-preview-129--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.

[DmitrySharabin]

Breaking: PropChangeEvent shape

PropChangeEvent now extends Event (not CustomEvent) and exposes its fields directly — e.value, e.oldValue, e.source, e.attributeName, etc. — instead of nesting under e.detail. Each dispatch gets a fresh event object; fields don't mutate past the handler.

Downstream impact (incl. color-elements): e.detail.* → e.* on propchange listeners.

I wonder if we should mention it in the docs just to draw the user's attention to the fact that we don't use event.details like they might expect for custom events. 🤔

[DmitrySharabin]

We have a couple of issues to fix. See comments.

[DmitrySharabin]

I'd also suggest adding these two regression tests:

{
      name: "Round-trip on one prop drops it; genuinely changed prop stays",
      async run () {
              let { element } = this.data;
              await flush(); // drain mount-time propschange
              this.data.propsEvents.length = 0;

              element.a = 5;
              element.a = 0; // back to stored default
              element.b = "new";

              await flush();
              return this.data.propsEvents;
      },
      arg: {
              props: {
                      a: { type: Number, default: 0 },
                      b: { type: String, default: "old" },
              },
      },
      expect: [[["b", "old"]]],
},
{
      name: "Re-entrant write from a propchange handler joins the same propschange",
      async run () {
              let { element } = this.data;
              await flush(); // drain mount-time propschange
              this.data.propsEvents.length = 0;

              element.addEventListener("propchange", e => {
                      if (e.name === "a") {
                              element.b = "from_listener";
                      }
              });

              element.a = "new";
              await flush();
              return this.data.propsEvents;
      },
      arg: { props: { a: { default: "foo" }, b: { default: "bar" } } },
      expect: [[["a", "foo"], ["b", "bar"]]],
}

[DmitrySharabin]

I'd suggest adding these tests (I believe they might help catch regressions). Other than that, LGTM! Excited to see what comes next.

[DmitrySharabin]

While testing the changes with the color elements, I found a regression. The default value of the color-inline component is calculated based on the component textContent:

value: {
	type: String,
	default () {
		return this.textContent.trim();
	},
}

The updated architecture where get is side-effect-free doesn't support such cases anymore. Here is a regression test.

{
    name: "default() that reads a non-prop (e.g. this.textContent) fires on mount",
    description:
        "A function default fires a mount event when it reads another prop, but not when it reads a non-prop receiver member:" +
        "  default () { return this.base }    // this.base is a prop → fires ✓" +
        "  default () { return this.content } // this.content isn't  → fires ✗ (BUG)" +
        "inferDependencies scrapes the name either way, promoting default() to a synthetic computed prop that depends on `content`. Since no such prop exists, nothing cascades to it and a computed prop doesn't self-fire on mount, so the chain stays silent. The value still derives correctly on read, but the mount propchange never fires.",
    arg: {
        mixin (Class) {
            Object.defineProperty(Class.prototype, "content", {
                get () {
                    return "hi";
                },
            });
        },
        props: {
            value: {
                default () {
                    return this.content;
                },
            },
        },
    },
    expect: [
        ["defaultValue", "hi"],
        ["value", "hi"],
    ],
}

[LeaVerou]

You mean it doesn't run at all? Or it doesn't re-run?

[DmitrySharabin]

You mean it doesn't run at all? Or it doesn't re-run?

Doesn't run at all. See

[LeaVerou]

Pushed a fix for the regression, feel free to add any tests you feel are useful

[LeaVerou]

@DmitrySharabin pushed ca48136 with the fix + your example as a regression test (full attribution in the test description).

Root cause was as you intuited — get() being side-effect-free in the refactored model exposed a latent gap. inferDependencies promotes any default() { return this.X } to a synthetic computed depending on X, but when X isn't a declared prop (textContent, a mixin getter, an instance field, etc.) nothing reactive sits on the other end of that edge, so no cascade ever fires. The pre-refactor code masked this because lazy reads of an orphaned defaultProp chain fired the mount event as a byproduct of get() resolving the value.

Fix: every prop's constructor now eagerly derives and fires its own mount event. Single-firing is preserved because a subsequent cascade-driven update() short-circuits on the equality check — the eager fire and the cascade can't both emit. Matches the principle that dependencies govern re-computation, not whether the initial derivation happens.

[DmitrySharabin]

We should fix this regression first: #129 (comment).

I also added these tests, so please pull.

[DmitrySharabin]

Should mount-drain propchanges be re-dispatched as semantic alias events?

This re-broadcasts every propchange — including the mount-time default fire — as its alias (spacechange, valuechange, …). So a consumer listening for the alias gets a "change" for a value that never changed (the initial default).

Real case that bit me: a parent listens to a nested child's spacechange and writes the child's value back into its own reflected prop:

// child: events = { spacechange: { propchange: "selectedSpace" } }   // selectedSpace is a computed (get) prop
spacePicker.addEventListener("spacechange", () => {
  this.value = spacePicker.value + "." + channelSelect.value; // ← also runs at mount
});

At mount the child's computed selectedSpace fires with its default (a98rgb), this listener re-fires it as spacechange, and the parent's authored value="oklab.a" gets overwritten (and reflected back to the attribute, destroying the markup). Because it races the parent's own value-sync, it's intermittent.

The catch is that for a computed aliased prop you can't filter it by source: both the mount fire and a genuine post-mount cascade arrive with source: undefined (ElementProp.update() clears it) — only oldValue === undefined separates them. And PropChangeEvent.applyTo keys off source, so it would also refuse to mirror real computed-prop changes.

So: should aliases fire during the mount drain for initial/default values at all — and if they do, what's the intended signal to tell "initial" from "changed"? (Pre-#106 these carried source: "initial", which at least gave consumers a marker to filter on.)

[LeaVerou]

I think the whole idea of applyTo() is fundamentally broken TBH. And for most callsites in color-elements replacing it would be a one line fix, I think. So I wonder if we should just get rid of it…

[DmitrySharabin]

With the adoption of updated({change}), none of the color elements use it. So, yes, we can get rid of it.

[DmitrySharabin]

Submitted a PR with possible fixes if it helps: #132.