@microsoft/webui-framework 0.0.12 → 0.0.13

package/dist/decorators.d.ts

@@ -36,6 +36,7 @@ export declare function getObservableNames(ctor: Function): Set<string>;
  *    only bindings that reference this property.
  */
 export declare function observable(target: object, name: string): void;
+export declare function isAttributeProperty(ctor: Function, property: string): boolean;
 /**
  * Like {@link observable} but also reflects to/from an HTML attribute
  * (kebab-case). The decorator patches `observedAttributes` and
@@ -56,5 +57,6 @@ export interface AttrOptions {
      *  Default is string mode (property receives the attribute string value). */
     mode?: 'boolean';
 }
+export declare function syncAttrProperties(instance: object, ctor: Function): void;
 export declare function attr(target: object, name: string): void;
 export declare function attr(options: AttrOptions): (target: object, name: string) => void;

package/dist/decorators.js

@@ -84,11 +84,12 @@ export function toKebabCase(str) {
     }
     return out;
 }
-/**
- * Shared logic for installing a reactive getter/setter on a class prototype.
- * The backing value is stored in a private `_prop` field on the instance.
- */
-function createReactiveProperty(proto, name) {
+const reflectingAttribute = Symbol('webui.reflectingAttribute');
+function parentConstructor(ctor) {
+    const parent = Object.getPrototypeOf(ctor);
+    return typeof parent === 'function' && parent !== Function.prototype ? parent : null;
+}
+function createReactiveProperty(proto, name, attrDefinition) {
     const backingKey = `_${name}`;
     const changedKey = `${name}Changed`;
     Object.defineProperty(proto, name, {
@@ -97,9 +98,12 @@ function createReactiveProperty(proto, name) {
         },
         set(newValue) {
             const oldValue = this[backingKey];
-            if (oldValue === newValue)
+            if (Object.is(oldValue, newValue))
                 return;
             this[backingKey] = newValue;
+            if (attrDefinition && this['$ready'] === true) {
+                reflectPropertyToAttribute(this, attrDefinition, newValue);
+            }
             const cb = this[changedKey];
             if (typeof cb === 'function') {
                 cb.call(this, oldValue, newValue);
@@ -114,6 +118,54 @@ function createReactiveProperty(proto, name) {
         configurable: true,
     });
 }
+function reflectPropertyToAttribute(instance, definition, value) {
+    const element = instance;
+    const attrName = definition.attribute;
+    if (definition.boolean) {
+        const shouldHaveAttribute = Boolean(value);
+        if (element.hasAttribute(attrName) === shouldHaveAttribute)
+            return;
+        setReflectingAttribute(instance, attrName);
+        try {
+            if (shouldHaveAttribute)
+                element.setAttribute(attrName, '');
+            else
+                element.removeAttribute(attrName);
+        }
+        finally {
+            restoreReflectingAttribute(instance);
+        }
+        return;
+    }
+    if (value == null) {
+        if (!element.hasAttribute(attrName))
+            return;
+        setReflectingAttribute(instance, attrName);
+        try {
+            element.removeAttribute(attrName);
+        }
+        finally {
+            restoreReflectingAttribute(instance);
+        }
+        return;
+    }
+    const attrValue = typeof value === 'string' ? value : String(value);
+    if (element.getAttribute(attrName) === attrValue)
+        return;
+    setReflectingAttribute(instance, attrName);
+    try {
+        element.setAttribute(attrName, attrValue);
+    }
+    finally {
+        restoreReflectingAttribute(instance);
+    }
+}
+function setReflectingAttribute(instance, attrName) {
+    instance[reflectingAttribute] = attrName;
+}
+function restoreReflectingAttribute(instance) {
+    instance[reflectingAttribute] = undefined;
+}
 // ---------------------------------------------------------------------------
 // @observable
 // ---------------------------------------------------------------------------
@@ -124,7 +176,21 @@ const observableRegistry = new WeakMap();
  */
 const EMPTY_SET = Object.freeze(new Set());
 export function getObservableNames(ctor) {
-    return observableRegistry.get(ctor) ?? EMPTY_SET;
+    const names = observableRegistry.get(ctor);
+    if (names)
+        return names;
+    const parent = parentConstructor(ctor);
+    return parent ? getObservableNames(parent) : EMPTY_SET;
+}
+function registerObservableProperty(ctor, name) {
+    let names = observableRegistry.get(ctor);
+    if (!names) {
+        const parent = parentConstructor(ctor);
+        const inherited = parent ? getObservableNames(parent) : EMPTY_SET;
+        names = inherited.size > 0 ? new Set(inherited) : new Set();
+        observableRegistry.set(ctor, names);
+    }
+    names.add(name);
 }
 /**
  * Marks a property as observable. When the value changes the decorator will:
@@ -134,10 +200,7 @@ export function getObservableNames(ctor) {
  */
 export function observable(target, name) {
     const ctor = target.constructor;
-    if (!observableRegistry.has(ctor)) {
-        observableRegistry.set(ctor, new Set());
-    }
-    observableRegistry.get(ctor).add(name);
+    registerObservableProperty(ctor, name);
     createReactiveProperty(target, name);
 }
 // ---------------------------------------------------------------------------
@@ -147,30 +210,74 @@ export function observable(target, name) {
  * Registry of attribute-name → property-name mappings per constructor.
  * Used by `attributeChangedCallback` to route attribute changes to properties.
  */
-const attrMap = new WeakMap();
-/** Registry of boolean-mode attribute names per constructor. */
-const boolAttrs = new WeakMap();
+const attrByAttribute = new WeakMap();
+/** Registry of property-name → attribute metadata, used for mount-time sync. */
+const attrByProperty = new WeakMap();
+function inheritedAttrMap(registry, ctor) {
+    let current = parentConstructor(ctor);
+    while (current) {
+        const map = registry.get(current);
+        if (map)
+            return map;
+        current = parentConstructor(current);
+    }
+    return undefined;
+}
+function attrDefinitionFor(ctor, attribute) {
+    let current = ctor;
+    while (current) {
+        const definition = attrByAttribute.get(current)?.get(attribute);
+        if (definition)
+            return definition;
+        current = parentConstructor(current);
+    }
+    return undefined;
+}
+function attrPropertyMapFor(ctor) {
+    let current = ctor;
+    while (current) {
+        const map = attrByProperty.get(current);
+        if (map)
+            return map;
+        current = parentConstructor(current);
+    }
+    return undefined;
+}
+export function isAttributeProperty(ctor, property) {
+    return attrPropertyMapFor(ctor)?.has(property) === true;
+}
 function applyAttr(target, name, options) {
     const proto = target;
     const ctor = proto.constructor;
-    // 1. Install the reactive getter/setter (same as @observable).
-    createReactiveProperty(proto, name);
-    // 2. Register the attribute mapping.
     const attrName = options?.attribute ?? toKebabCase(name);
-    if (!attrMap.has(ctor)) {
-        attrMap.set(ctor, new Map());
+    const definition = {
+        attribute: attrName,
+        property: name,
+        boolean: options?.mode === 'boolean',
+    };
+    // 1. Install the reactive getter/setter (same as @observable), with
+    // attribute reflection enabled after the element finishes hydration.
+    registerObservableProperty(ctor, name);
+    createReactiveProperty(proto, name, definition);
+    // 2. Register the attribute mapping.
+    let byAttribute = attrByAttribute.get(ctor);
+    if (!byAttribute) {
+        const inherited = inheritedAttrMap(attrByAttribute, ctor);
+        byAttribute = inherited ? new Map(inherited) : new Map();
+        attrByAttribute.set(ctor, byAttribute);
     }
-    attrMap.get(ctor).set(attrName, name);
-    // Track boolean-mode attrs.
-    if (options?.mode === 'boolean') {
-        if (!boolAttrs.has(ctor)) {
-            boolAttrs.set(ctor, new Set());
-        }
-        boolAttrs.get(ctor).add(attrName);
+    byAttribute.set(attrName, definition);
+    let byProperty = attrByProperty.get(ctor);
+    if (!byProperty) {
+        const inherited = inheritedAttrMap(attrByProperty, ctor);
+        byProperty = inherited ? new Map(inherited) : new Map();
+        attrByProperty.set(ctor, byProperty);
     }
+    byProperty.set(name, definition);
     // 3. Accumulate observed attributes on the constructor.
-    if (!ctor._observedAttrs) {
-        ctor._observedAttrs = [];
+    if (!Object.prototype.hasOwnProperty.call(ctor, '_observedAttrs')) {
+        const inheritedAttrs = ctor._observedAttrs;
+        ctor._observedAttrs = inheritedAttrs ? inheritedAttrs.slice() : [];
         // Define the static getter that `customElements.define` inspects.
         Object.defineProperty(ctor, 'observedAttributes', {
             get() {
@@ -182,11 +289,12 @@ function applyAttr(target, name, options) {
         const origACB = proto['attributeChangedCallback'];
         proto['attributeChangedCallback'] = function (attribute, oldVal, newVal) {
             // Route the attribute change to the corresponding property.
-            const map = attrMap.get(this.constructor);
-            const propName = map?.get(attribute);
-            if (propName !== undefined) {
-                const isBool = boolAttrs.get(this.constructor)?.has(attribute);
-                this[propName] = isBool ? newVal !== null : newVal;
+            const definition = attrDefinitionFor(this.constructor, attribute);
+            if (definition !== undefined &&
+                this[reflectingAttribute] !== attribute) {
+                this[definition.property] = definition.boolean
+                    ? newVal !== null
+                    : newVal;
             }
             // Preserve any pre-existing attributeChangedCallback.
             if (origACB) {
@@ -196,6 +304,15 @@ function applyAttr(target, name, options) {
     }
     ctor._observedAttrs.push(attrName);
 }
+export function syncAttrProperties(instance, ctor) {
+    const attrs = attrPropertyMapFor(ctor);
+    if (!attrs)
+        return;
+    const reactiveInstance = instance;
+    for (const definition of attrs.values()) {
+        reflectPropertyToAttribute(reactiveInstance, definition, reactiveInstance[definition.property]);
+    }
+}
 export function attr(targetOrOptions, name) {
     if (typeof name === 'string') {
         applyAttr(targetOrOptions, name);

package/dist/element.d.ts

@@ -81,6 +81,14 @@ export declare class WebUIElement extends HTMLElement {
      * Starts searching from `after` (exclusive) if provided, or from firstChild.
      */
     private $findMarker;
+    /**
+     * Check whether there is non-marker content between a conditional
+     * start anchor and its closing marker.  Used during SSR hydration to
+     * detect server-rendered conditional content even when the runtime
+     * condition value has not been set yet (e.g. complex property from a
+     * parent repeat binding that hydrates after its children).
+     */
+    private $hasContentAfterMarker;
     /**
      * Find existing SSR text node by mapping template text-node ordinal.
      *

package/dist/element.js

@@ -40,7 +40,7 @@
  */
 import { getTemplate } from './template.js';
 import { hydrationStart, hydrationEnd } from './lifecycle.js';
-import { getObservableNames } from './decorators.js';
+import { getObservableNames, isAttributeProperty, syncAttrProperties } from './decorators.js';
 import { syncRepeat, dotWalk } from './element/diff.js';
 import { collectItemMarkers, nextElement, findByOrdinal, MARKER_COND_START, MARKER_COND_END, MARKER_REPEAT_START, } from './element/markers.js';
 import { injectModuleStyle, } from './element/styles.js';
@@ -201,6 +201,7 @@ export class WebUIElement extends HTMLElement {
         this.$meta = meta;
         this.$hydrated = true;
         this.$ready = true;
+        syncAttrProperties(this, this.constructor);
         // Client-created components: flush current attr/observable values
         // into the freshly-wired template DOM. Call $updateInstance directly
         // to avoid the $update() path-index build — it will be lazy-built
@@ -299,9 +300,10 @@ export class WebUIElement extends HTMLElement {
         const state = window.__webui?.state;
         if (!state || typeof state !== 'object')
             return;
-        const names = getObservableNames(this.constructor);
+        const ctor = this.constructor;
+        const names = getObservableNames(ctor);
         for (const key of Object.keys(state)) {
-            if (names.has(key)) {
+            if (names.has(key) && !isAttributeProperty(ctor, key)) {
                 // Write to backing field directly — no reactive update yet
                 this[`_${key}`] = state[key];
             }
@@ -639,8 +641,18 @@ export class WebUIElement extends HTMLElement {
                 }
                 if (marker)
                     lastCondMarker = marker;
-                if (shown && blockMeta && marker) {
-                    condInstance = this.$hydrateCondContent(condAnchor, blockMeta, scope);
+                // SSR hydration: if the marker exists, the server rendered this
+                // conditional — hydrate its content regardless of the current
+                // condition value.  Complex properties from parent bindings may
+                // not have arrived yet (the parent hydrates after children), so
+                // the condition could evaluate to false even though the server
+                // rendered it as true.  Trust the SSR DOM and wire it up; the
+                // condition will re-evaluate correctly once all data is set.
+                const ssrContentPresent = marker && blockMeta && this.$hasContentAfterMarker(condAnchor, MARKER_COND_END);
+                if (blockMeta && (shown || ssrContentPresent)) {
+                    if (marker) {
+                        condInstance = this.$hydrateCondContent(condAnchor, blockMeta, scope);
+                    }
                 }
                 // Collect <!--/wc--> end marker for deferred removal.
                 // Do NOT remove here — later phases (repeats, events) still need
@@ -830,9 +842,12 @@ export class WebUIElement extends HTMLElement {
             // Single-root optimisation: hydrate the element in-place (pathStart=1).
             const el = nextElement(condAnchor);
             if (el) {
-                const inst = this.$hydrate(el, blockMeta, tplDom, scope, 1);
-                this.$updateInstance(inst);
-                return inst;
+                // Wire bindings only — do NOT call $updateInstance.  SSR text
+                // nodes already contain correct values; evaluating bindings now
+                // would overwrite them with stale data (e.g. a complex property
+                // from a parent that hasn't hydrated yet).  This is consistent
+                // with $mount which also skips $updateInstance for SSR roots.
+                return this.$hydrate(el, blockMeta, tplDom, scope, 1);
             }
             return null;
         }
@@ -850,7 +865,7 @@ export class WebUIElement extends HTMLElement {
             condAnchor.parentNode?.insertBefore(inst.nodes[cn], afterNode.nextSibling);
             afterNode = inst.nodes[cn];
         }
-        this.$updateInstance(inst);
+        // Same as above — trust SSR DOM, skip binding evaluation.
         return inst;
     }
     /**
@@ -867,6 +882,23 @@ export class WebUIElement extends HTMLElement {
         }
         return null;
     }
+    /**
+     * Check whether there is non-marker content between a conditional
+     * start anchor and its closing marker.  Used during SSR hydration to
+     * detect server-rendered conditional content even when the runtime
+     * condition value has not been set yet (e.g. complex property from a
+     * parent repeat binding that hydrates after its children).
+     */
+    $hasContentAfterMarker(anchor, endData) {
+        let sibling = anchor.nextSibling;
+        while (sibling) {
+            if (sibling.nodeType === 8 && sibling.data === endData) {
+                return false; // reached end marker with no content in between
+            }
+            return true; // any non-end-marker node = content present
+        }
+        return false;
+    }
     /**
      * Find existing SSR text node by mapping template text-node ordinal.
      *
@@ -1050,36 +1082,66 @@ export class WebUIElement extends HTMLElement {
             const root = dot > -1 ? path.slice(0, dot) : path;
             return observableNames.has(root) ? root : '*';
         };
-        const r = this.$root;
-        for (const t of r.texts) {
-            if (t.parts) {
-                for (const p of t.parts) {
-                    if (typeof p !== 'string')
-                        ensure(keyFor(p[0])).texts.push(t);
+        const isLocalPath = (path, scope) => {
+            const dot = path.indexOf('.');
+            const root = dot > -1 ? path.slice(0, dot) : path;
+            let current = scope;
+            while (current) {
+                if (current.name === root)
+                    return true;
+                current = current.parent;
+            }
+            return false;
+        };
+        const visit = (instance) => {
+            for (const t of instance.texts) {
+                if (t.parts) {
+                    for (const p of t.parts) {
+                        if (typeof p !== 'string' && !isLocalPath(p[0], t.scope)) {
+                            ensure(keyFor(p[0])).texts.push(t);
+                        }
+                    }
+                }
+                else if (t.path && !isLocalPath(t.path, t.scope)) {
+                    ensure(keyFor(t.path)).texts.push(t);
                 }
             }
-        }
-        for (const a of r.attrs) {
-            if (a.path)
-                ensure(keyFor(a.path)).attrs.push(a);
-            if (a.parts) {
-                for (const p of a.parts) {
-                    if (typeof p !== 'string')
-                        ensure(keyFor(p[0])).attrs.push(a);
+            for (const a of instance.attrs) {
+                if (a.path && !isLocalPath(a.path, a.scope)) {
+                    ensure(keyFor(a.path)).attrs.push(a);
+                }
+                if (a.parts) {
+                    for (const p of a.parts) {
+                        if (typeof p !== 'string' && !isLocalPath(p[0], a.scope)) {
+                            ensure(keyFor(p[0])).attrs.push(a);
+                        }
+                    }
+                }
+                if (a.condition) {
+                    for (const p of a.condition[1]) {
+                        if (!isLocalPath(p, a.scope))
+                            ensure(keyFor(p)).attrs.push(a);
+                    }
+                }
+            }
+            for (const c of instance.conds) {
+                for (const p of c.condition[1]) {
+                    if (!isLocalPath(p, c.scope))
+                        ensure(keyFor(p)).conds.push(c);
                 }
+                if (c.instance)
+                    visit(c.instance);
             }
-            if (a.condition) {
-                for (const p of a.condition[1])
-                    ensure(keyFor(p)).attrs.push(a);
+            for (const rep of instance.repeats) {
+                if (!isLocalPath(rep.collection, rep.scope)) {
+                    ensure(keyFor(rep.collection)).repeats.push(rep);
+                }
+                for (let i = 0; i < rep.instances.length; i++) {
+                    visit(rep.instances[i].instance);
+                }
             }
-        }
-        for (const c of r.conds) {
-            for (const p of c.condition[1])
-                ensure(keyFor(p)).conds.push(c);
-        }
-        for (const rep of r.repeats) {
-            ensure(keyFor(rep.collection)).repeats.push(rep);
-        }
+        };
+        visit(this.$root);
         // Store wildcard bindings separately — avoids duplicating them into every path
         const wc = index.get('*');
         if (wc) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/webui-framework",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "type": "module",
   "description": "WebUI Framework Next — Preact-inspired lightweight Web Component runtime with SSR hydration. 15KB minified, compiled-template path mapping, no hydration markers.",
   "license": "MIT",
@@ -19,7 +19,7 @@
     "@playwright/test": "^1.58.2",
     "@types/node": "^25.3.5",
     "typescript": "^5.9.3",
-    "@microsoft/webui-test-support": "0.0.12"
+    "@microsoft/webui-test-support": "0.0.13"
   },
   "scripts": {
     "build": "tsc",