feat: add reflect option to useProperty for property-attribute reflection

[cristinecula]

Note: This is one of three alternative implementations for NEO-1055. See also:

• feat: add useAttribute hook for self-contained property-attribute reflection #97 — Standalone useAttribute hook (self-contained, MutationObserver-based, multi-type support)
• feat: add useAttribute hook for boolean property ↔ attribute reflection #99 — Standalone useAttribute hook (boolean-only, cooperative with component.ts)

Summary

Adds a reflect option to useProperty that enables bidirectional property-attribute synchronization with built-in loop prevention.

• Extend useProperty with optional { reflect: true } third argument
• Add reflectingSymbol to symbols.ts for loop guard
• Modify attributeChangedCallback in component.ts to respect the guard and convert null (attribute removal) to false

Closes NEO-1055

API

const [opened, setOpened] = useProperty<boolean>('opened', false, { reflect: true });

Behavior:

• Property → attribute: when the property changes, reflect to the HTML attribute (setAttribute/removeAttribute)
• Attribute → property: when the attribute changes (via attributeChangedCallback), sync to the property
• Loop guard: a Symbol("haunted.reflecting") flag on the host prevents attributeChangedCallback from re-setting the property during reflection
• Boolean coercion: false/null/undefined → remove attribute; true → set empty string attribute; other values → setAttribute(name, String(value))

Changes

1. src/symbols.ts — New reflectingSymbol

const reflectingSymbol = Symbol("haunted.reflecting");

Follows existing Symbol("haunted.xyz") convention. Symbol keys are handled by the proxy as non-reactive plain properties.

2. src/component.ts — attributeChangedCallback changes

attributeChangedCallback(name, oldValue, newValue) {
    if (oldValue === newValue) return;
    if (this[reflectingSymbol]) return;   // skip self-initiated reflection
    let val = newValue === "" ? true : newValue;
    if (val === null) val = false;        // attribute removal → false
    Reflect.set(this, toCamelCase(name), val);
}

• reflectingSymbol guard: When useProperty reflects a property to an attribute, it sets host[reflectingSymbol] = true. The callback checks this and skips processing, preventing the feedback loop.
• null → false: Attribute removal now produces false instead of null. Verified safe across all existing consumers.

3. src/use-property.ts — reflect option

• New UsePropertyOptions interface with optional reflect: boolean
• New attrName, reflect, and lastReflected fields on the Hook class
• New reflectToAttribute(value) method wrapping setAttribute/removeAttribute in reflectingSymbol guard
• In constructor: if reflecting and host has the attribute, read initial value from attribute
• In updateProp(): after setting property, call reflectToAttribute() if reflecting
• In update(): reflect on re-render when value changed externally (e.g. parent sets property via binding)
• Updated TypeScript overloads for the third parameter

4. Tests

10 new test cases:

• Reflects boolean property to/from attribute
• Reflects string property to/from attribute
• No feedback loop (setting property reflects without infinite recursion)
• Attribute → property sync (requires observedAttributes)
• Attribute removal syncs property to false
• Initial attribute value is honored
• Does not reflect when event is prevented
• Backward compatible (existing useProperty unchanged)
• Works with lift() integration
• null → false in attributeChangedCallback (in attrs.test.ts)

Consumer Migration

Before (manual reflection with feedback loop risk):

const [opened, setOpened] = useProperty<boolean>('opened', false);
useEffect(() => { host.toggleAttribute('opened', !!opened); }, [opened]);
// 'opened' excluded from observedAttributes to avoid loop

After:

const [opened, setOpened] = useProperty<boolean>('opened', false, { reflect: true });
// 'opened' can now safely be in observedAttributes

Notes

• Consumers must still declare reflected attributes in observedAttributes for attribute → property sync (web platform limitation: observedAttributes is static)
• Property → attribute reflection works regardless of observedAttributes
• The reflectingSymbol is set synchronously around setAttribute/removeAttribute calls, so there's no async timing concern

[netlify]

✅ Deploy Preview for pionjs ready!

Name	Link
🔨 Latest commit	7004a53
🔍 Latest deploy log	https://app.netlify.com/projects/pionjs/deploys/6992d0b4724dbd00084fa4e4
😎 Deploy Preview	https://deploy-preview-100--pionjs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7004a53

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR