Convergent restore-default for reflected props

[DmitrySharabin]

Summary

Builds on #108 (regression fixes) to add the clear-stale-attribute behavior for reflected props. After this PR, el.prop = undefined and el.removeAttribute(name) converge — both revert the prop to the default and clear any previously-reflected attribute.

Stacked on #102. #108 lands first.

Behavior

Action	After #108	After this PR
el.bar = X (where X ≠ default)	el.bar=X, attr="X"	el.bar=X, attr="X"
el.bar = X where X = default	el.bar=X, attr="X"	el.bar=X, attr="X"
el.bar = undefined after a prior write	el.bar=default, attr stays X	el.bar=default, attr=null
el.removeAttribute("bar") after a prior write	el.bar=default, attr=null	el.bar=default, attr=null
Reactive default re-evaluates while a stale attribute lingers	attr stays X	attr=null

The "stays X" rows are a latent bug present even on pre-signals (the old applyChange helper's ?? element.getAttribute(...) treats explicit null as "use fallback" and silently leaks a stale attribute). Not technically a regression — but worth fixing alongside the convergent-restore contracts.

Implementation

• #reflect(element, value, source) — extends the helper Restore pre-signals defaults / reflection behavior (closes #105) #108 introduces. Maps source === "default" to a null attribute target; the existing "write if different" logic does the rest, naturally clearing stale attributes without a separate code path.
• #settle(element, value) — single source of truth for the default → parse → convert pipeline. Used from the Computed body and from Prop#set's rawSignal path so the inline reflection (introduced in Restore pre-signals defaults / reflection behavior (closes #105) #108) sees the same settled value.

Trade-offs

• Reflection is decoupled from the propchange event. Explicit writes always reflect; events follow value-change semantics. Writing the current default-resolved value reflects to the DOM but doesn't fire propchange (consistent with the renamed Assigning current default-resolved value is a no-op for events test).
• el.prop = null is preserved as a legitimate user value (mirrors JS conventions). Use undefined or removeAttribute() to restore the default.

Test plan

• npm test -- --ci — 101/102 PASS, 0 FAIL, 1 pre-existing skip in split()
• All 4 scenarios from the review comment exercised in tests

Rebase note

This branch's current diff still includes parts of #108 (the regression fixes). Once #108 lands and this branch rebases on the new main, those commits dedupe automatically. The substantive remainder is 1c8149c (data-flow encoding for stale-attribute clearing), 568c6e2 (#settle extraction), e3f2180 (docs), and the test additions.

[LeaVerou]

This reminds me, defaults are one case where updated() consumers may want to read either the internal value or the getter value. They can always get the current getter value via the actual getter, but not the old value.

[LeaVerou]

Before I review the code, one thing I want to make sure (and we should have tests for) is that the behavior is as expected.

Suppose you have element <x-foo> with attribute bar with a default value of 5 that reflects both ways.

• <x-foo></x-foo> → should not reflect, foo.bar returns 5
• <x-foo id=foo></x-foo> with JS doing foo.bar = 5; should reflect (you see <x-foo bar="5"></x-foo> in the DOM)
• foo.bar = undefined; foo.bar should return undefined, not 5 (though if that complicates implementation, we can revisit)
• <x-foo id=foo bar="6"></x-foo> and then foo.removeAttribute("bar"); foo.bar; → returns 5

[DmitrySharabin]

I added the corresponding tests. I just would like to discuss one case.

Let's consider the following definition of <x-foo>:

import NudeElement from "nude-element";

class XFoo extends NudeElement {
	static props = {
		bar: {
			type: Number,
			default: 5,
			reflect: true, // spelled out for clarity
		},
	};
}

customElements.define("x-foo", XFoo);

• <x-foo></x-foo> → should not reflect, foo.bar returns 5

This is how it works now. No changes required.

• <x-foo id=foo></x-foo> with JS doing foo.bar = 5; should reflect (you see <x-foo bar="5"></x-foo> in the DOM)

Because bar has a default value, its value is stored in rawSignal and wrapped by a computed signal. After the element is mounted, the computed signal has emitted 5 (from default fallthrough). Then foo.bar = 5 writes 5 into rawSignal, and the computed one re-evaluates to 5. But the computed's equals(5, 5) is true, so it short-circuits and never notifies its subscriber. That subscriber is what drives both reflection and the propchange event, so neither happens.

With the recent changes, it also works as you described. The reflection is decoupled from the computed dedupe via an inline path in Prop#set, so the user's write reaches the DOM. The propchange event, however, still follows value-change semantics: writing the current value is a no-op for events.

• foo.bar = undefined; foo.bar should return undefined, not 5 (though if that complicates implementation, we can revisit)

Writing foo.bar = undefined clears rawSignal back to undefined, which the computed wrapper then resolves to 5 via the default. This is also what makes defaultProp work since it desugars to default() { return this[other] } and relies on writing undefined to restore the link after an explicit write severs it (see the “defaultProp restores on undefined” test).

Returning undefined in this case would require a separate “user explicitly set to undefined” sentinel—distinct from “rawSignal is at its initial state”. This is a bigger change that would also need a new way for defaultProp consumers to re-engage the link.

• <x-foo id=foo bar="6"></x-foo> and then foo.removeAttribute("bar"); foo.bar; → returns 5

It also works with the recent changes.

[LeaVerou]

Yeah, the important bit is to distinguish "explicitly set to default value" from "set to default value because no value has been set". E.g. a button component may default to variant=neutral (and in the CSS you may treat it as "neutral unless something else is inherited"), but that's fundamentally different from explicitly setting its variant to neutral.

undefined is less important, since components can always use another value to mean empty, so it's ok if undefined is always converted to the default value — I think. If anything, it gives consumers an explicit way to reset to the default value.

[DmitrySharabin]

Superseded by #108 — the stale-attribute clearing was bundled into the same default-reflection logic in #108. The simplified diff is a 4-line tweak in #onComputedChange (#108) plus a regression test.