@microsoft/webui-framework 0.0.29 → 0.0.30

package/README.md

@@ -12,7 +12,7 @@ This package is the browser-side runtime used by `webui build --plugin=webui`. I
 
 If you are building WebUI apps in this repo, this is the component model used by examples like `examples/app/todo-webui`, `examples/app/commerce`, and `examples/app/contact-book-manager`.
 
-> 📖 **Full documentation at [microsoft.github.io/webui](https://microsoft.github.io/webui)**, see the [Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity) for component authoring patterns. For framework internals (hydration, path resolution, reactive update model), see [RENDERING.md](./RENDERING.md).
+> 📖 **Full documentation at [microsoft.github.io/webui](https://microsoft.github.io/webui)**, see the [Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity) for component authoring patterns. For framework internals (hydration, path resolution, reactive update model), see [the hydration contract](https://github.com/microsoft/webui/blob/main/specs/hydration.md).
 
 ## Install
 
@@ -328,7 +328,7 @@ update that DOM, so the write is dropped and the runtime logs a
 `[WebUI] Hydration mismatch` warning naming the properties. Seed such values in
 the SSR state, or assign them from `hydratedCallback()`. The warning is
 development-only and is dead-code-eliminated from production bundles via the
-`__WEBUI_DEV__` compile-time flag (on by default; `webui-press build` sets it to
+`__WEBUI_DEV__` compile-time flag (on by default; `webui press build` sets it to
 `false`). See the
 [Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity#setting-observable-state-during-setup).
 

package/dist/decorators.js

@@ -162,6 +162,12 @@ function createReactiveProperty(proto, name, attrDefinition) {
             return this[backingKey];
         },
         set(newValue) {
+            const captured = this['$preUpgradeProperties'];
+            if (captured?.has(name) && this.matches(':defined')) {
+                captured.delete(name);
+                if (captured.size === 0)
+                    this['$preUpgradeProperties'] = undefined;
+            }
             const oldValue = this[backingKey];
             if (Object.is(oldValue, newValue)) {
                 if (this['$deferredSSR'] === true) {
@@ -172,12 +178,33 @@ function createReactiveProperty(proto, name, attrDefinition) {
                 return;
             }
             this[backingKey] = newValue;
-            if (attrDefinition && this['$ready'] === true) {
-                reflectPropertyToAttribute(this, attrDefinition, newValue);
+            let canReflect = false;
+            if (attrDefinition) {
+                const checkReflection = this['$canRunAuthoredEffects'];
+                if (typeof checkReflection === 'function' &&
+                    checkReflection.call(this)) {
+                    reflectPropertyToAttribute(this, attrDefinition, newValue);
+                    canReflect = true;
+                }
             }
-            const cb = this[changedKey];
-            if (typeof cb === 'function') {
-                cb.call(this, oldValue, newValue);
+            const callback = this[changedKey];
+            if (typeof callback === 'function') {
+                if (this['$authoredPhase'] === 1 &&
+                    (attrDefinition ? canReflect : this.isConnected)) {
+                    callback
+                        .call(this, oldValue, newValue);
+                }
+                else {
+                    const record = this['$recordPropertyChange'];
+                    if (typeof record === 'function') {
+                        record
+                            .call(this, name, oldValue);
+                    }
+                    else {
+                        callback
+                            .call(this, oldValue, newValue);
+                    }
+                }
             }
             if (this.isConnected ||
                 this['$deferredSSR'] === true) {
@@ -234,9 +261,16 @@ function applyAttr(target, name, options) {
             const definition = attrDefinitionFor(this.constructor, attribute);
             if (definition !== undefined &&
                 this[reflectingAttribute] !== attribute) {
-                this[definition.property] = definition.boolean
-                    ? newVal !== null
-                    : newVal;
+                const captured = this['$preUpgradeProperties'];
+                if (captured)
+                    this['$preUpgradeProperties'] = undefined;
+                try {
+                    this[definition.property] = definition.boolean ? newVal !== null : newVal;
+                }
+                finally {
+                    if (captured)
+                        this['$preUpgradeProperties'] = captured;
+                }
             }
             if (origACB) {
                 origACB.call(this, attribute, oldVal, newVal);

package/dist/element.d.ts

@@ -4,6 +4,18 @@ import type { TemplateBlockMeta, TemplateMeta, TemplateNodeIndex } from './templ
 import type { ScopeFrame, TemplateInstance } from './element/types.js';
 export declare class WebUIElement extends TemplateElement {
     private $lazyHydrationMode;
+    private $authoredPhase;
+    private $pendingPropertyChanges;
+    private $preUpgradeProperties;
+    constructor();
+    connectedCallback(): void;
+    $destroy(): void;
+    $recordPropertyChange(name: string, oldValue: unknown): void;
+    protected $reconcileAuthoredState(): boolean;
+    $flushUpdates(): void;
+    private $flushAuthoredChanges;
+    private $invokePropertyChange;
+    private $releasePropertyChanges;
     protected $shouldDeferSSRHydration(meta?: TemplateMeta): boolean;
     protected $didDeferSSRHydration(): void;
     protected $didDeferStreamedSSRHydration(state: Record<string, unknown> | undefined): void;

package/dist/element.js

@@ -7,6 +7,9 @@ const RENDER_ATTR = 'w-render';
 const HYDRATE_EAGER = 'eager';
 const INTERACTION_HYDRATION = 3;
 const LAZY_RENDER_INTERACTION = 4;
+const AUTHORED_LIVE = 1;
+const AUTHORED_PENDING = 2;
+const AUTHORED_FLUSHING = 4;
 const DEV = typeof __WEBUI_DEV__ === 'undefined' || __WEBUI_DEV__;
 let warnedMissingLazyHydrationEntry = false;
 function warnMissingLazyHydrationEntry(tag, policy) {
@@ -22,6 +25,121 @@ function warnMissingLazyHydrationEntry(tag, policy) {
         'your component definitions to enable visibility-deferred hydration.');
 }
 export class WebUIElement extends TemplateElement {
+    constructor() {
+        super();
+        const names = getObservableNames(this.constructor);
+        for (const name of names) {
+            if (!Object.prototype.hasOwnProperty.call(this, name))
+                continue;
+            (this.$preUpgradeProperties ??= new Map()).set(name, this[name]);
+            delete this[name];
+        }
+    }
+    connectedCallback() {
+        const properties = this.$preUpgradeProperties;
+        if (properties) {
+            this.$preUpgradeProperties = undefined;
+            for (const [name, value] of properties) {
+                this[name] = value;
+            }
+        }
+        super.connectedCallback();
+    }
+    $destroy() {
+        if (this.$authoredPhase !== undefined)
+            this.$authoredPhase &= ~AUTHORED_LIVE;
+        super.$destroy();
+    }
+    $recordPropertyChange(name, oldValue) {
+        if (this.$authoredPhase === undefined)
+            return;
+        const changes = this.$pendingPropertyChanges;
+        if ((this.$authoredPhase & AUTHORED_LIVE) && this.$canRunAuthoredEffects()) {
+            if (changes?.has(name)) {
+                oldValue = changes.get(name);
+                changes.delete(name);
+            }
+            try {
+                this.$invokePropertyChange(name, oldValue);
+            }
+            finally {
+                this.$releasePropertyChanges();
+            }
+        }
+        else {
+            const queued = changes ?? (this.$pendingPropertyChanges = new Map());
+            if (!queued.has(name))
+                queued.set(name, oldValue);
+            this.$authoredPhase |= AUTHORED_PENDING;
+        }
+    }
+    $reconcileAuthoredState() {
+        if (!this.$canRunAuthoredEffects())
+            return !this.$pendingPropertyChanges;
+        if (this.$authoredPhase === undefined) {
+            const names = getObservableNames(this.constructor);
+            for (const name of names) {
+                if (typeof this[`${name}Changed`] !== 'function')
+                    continue;
+                this.$authoredPhase = AUTHORED_LIVE;
+                if (Object.prototype.hasOwnProperty.call(this, `_${name}`)) {
+                    (this.$pendingPropertyChanges ??= new Map()).set(name, undefined);
+                }
+            }
+        }
+        if (this.$authoredPhase === undefined)
+            return true;
+        this.$authoredPhase |= AUTHORED_LIVE;
+        if (this.$authoredPhase & AUTHORED_FLUSHING)
+            return false;
+        if (this.$pendingPropertyChanges) {
+            this.$authoredPhase |= AUTHORED_PENDING;
+            this.$flushAuthoredChanges();
+        }
+        return !this.$pendingPropertyChanges;
+    }
+    $flushUpdates() {
+        if (this.$pendingPropertyChanges)
+            this.$notifyHydrated();
+        super.$flushUpdates();
+    }
+    $flushAuthoredChanges() {
+        const changes = this.$pendingPropertyChanges;
+        if (!changes || !this.$canRunAuthoredEffects())
+            return;
+        this.$authoredPhase = AUTHORED_LIVE | AUTHORED_PENDING | AUTHORED_FLUSHING;
+        try {
+            for (const [name, oldValue] of changes) {
+                if (!this.$canRunAuthoredEffects()) {
+                    this.$authoredPhase &= ~AUTHORED_LIVE;
+                    break;
+                }
+                changes.delete(name);
+                this.$invokePropertyChange(name, oldValue);
+            }
+        }
+        finally {
+            this.$authoredPhase &= ~AUTHORED_FLUSHING;
+            this.$releasePropertyChanges();
+        }
+    }
+    $invokePropertyChange(name, oldValue) {
+        const value = this[name];
+        if (Object.is(oldValue, value))
+            return;
+        const callback = this[`${name}Changed`];
+        if (typeof callback === 'function') {
+            callback.call(this, oldValue, value);
+        }
+    }
+    $releasePropertyChanges() {
+        const phase = this.$authoredPhase;
+        if (phase !== undefined && this.$pendingPropertyChanges?.size === 0 &&
+            !(phase & AUTHORED_FLUSHING)) {
+            this.$pendingPropertyChanges = undefined;
+            this.$authoredPhase = phase & ~AUTHORED_PENDING;
+        }
+    }
     $shouldDeferSSRHydration(meta) {
         this.$lazyHydrationMode = this.$resolveLazyHydrationMode(meta);
         return this.$lazyHydrationMode !== undefined;
@@ -90,6 +208,8 @@ export class WebUIElement extends TemplateElement {
         this.$activateDeferredSSR(state);
     }
     disconnectedCallback() {
+        if (this.$authoredPhase !== undefined)
+            this.$authoredPhase &= ~AUTHORED_LIVE;
         if (this.$lazyHydrationMode !== undefined) {
             disconnectLazyHydration(this);
         }
@@ -103,7 +223,8 @@ export class WebUIElement extends TemplateElement {
         return attribute === undefined || !this.hasAttribute(attribute);
     }
     $syncAuthoredAttributes() {
-        syncAttrProperties(this, this.constructor);
+        if (this.isConnected)
+            syncAttrProperties(this, this.constructor);
     }
     $emit(name, detail) {
         return this.dispatchEvent(new CustomEvent(name, {

package/dist/template-element.d.ts

@@ -19,7 +19,7 @@ export declare class TemplateElement extends HTMLElement {
     private $hydrated;
     private $deferredClientMount;
     private $resetClientShadow;
-    private $hasMounted;
+    private $mountPhase;
     private $deferredSSR;
     private $activatingDeferredSSR;
     private $deferredAncestor;
@@ -78,7 +78,7 @@ export declare class TemplateElement extends HTMLElement {
     protected $shouldApplySSRState(_key: string): boolean;
     protected $syncAuthoredAttributes(): void;
     protected hydratedCallback(): void;
-    private $notifyHydrated;
+    protected $notifyHydrated(): void;
     private $finishHydration;
     protected $shouldApplyTemplateStateFromSSR(_key: string): boolean;
     protected $setTemplateState(key: string, value: unknown): boolean;
@@ -93,6 +93,8 @@ export declare class TemplateElement extends HTMLElement {
     private $recordDeferredWrite;
     private $replayDeferredWrites;
     $flushUpdates(): void;
+    protected $reconcileAuthoredState(): boolean;
+    protected $canRunAuthoredEffects(): boolean;
     private $flush;
     private $recordPreReadyWrite;
     private $checkHydrationMismatch;

package/dist/template-element.js

@@ -204,6 +204,8 @@ function hasAuthoredMember(instance, key) {
     }
     return false;
 }
+const MOUNTED = 1;
+const HYDRATION_NOTIFIED = 2;
 export class TemplateElement extends HTMLElement {
     constructor() {
         super(...arguments);
@@ -212,7 +214,7 @@ export class TemplateElement extends HTMLElement {
         this.$hydrated = false;
         this.$deferredClientMount = false;
         this.$resetClientShadow = false;
-        this.$hasMounted = false;
+        this.$mountPhase = 0;
         this.$deferredSSR = false;
         this.$activatingDeferredSSR = false;
         this.$hasUnknownScopes = false;
@@ -322,6 +324,8 @@ export class TemplateElement extends HTMLElement {
             hydrationStart();
             try {
                 this.$ready = true;
+                this.$syncAuthoredAttributes();
+                this.$notifyHydrated();
                 this.$update();
             }
             finally {
@@ -329,7 +333,7 @@ export class TemplateElement extends HTMLElement {
             }
             return;
         }
-        if (!this.$hasMounted &&
+        if (!this.$mountPhase &&
             isStreamingHydrationMode() &&
             this.hasAttribute(STREAMED_HOST_ATTR)) {
             this.$deferredSSR = true;
@@ -346,7 +350,7 @@ export class TemplateElement extends HTMLElement {
             return;
         }
         this.$meta = meta;
-        if (this.$hasMounted) {
+        if (this.$mountPhase) {
             this.$remount(meta);
         }
         else {
@@ -856,10 +860,14 @@ export class TemplateElement extends HTMLElement {
     hydratedCallback() {
     }
     $notifyHydrated() {
-        if (this.$hasMounted)
+        if (!this.$mountPhase)
+            this.$mountPhase = MOUNTED;
+        if (!this.$reconcileAuthoredState())
             return;
-        this.$hasMounted = true;
-        this.hydratedCallback();
+        if (this.$mountPhase === MOUNTED) {
+            this.$mountPhase = HYDRATION_NOTIFIED;
+            this.hydratedCallback();
+        }
     }
     $finishHydration() {
         let callbackFailed = false;
@@ -1031,9 +1039,18 @@ export class TemplateElement extends HTMLElement {
         this.$flush(true);
     }
     $flushUpdates() {
+        if (this.$mountPhase === MOUNTED)
+            this.$notifyHydrated();
         if (this.$pendingFlush)
             this.$flush();
     }
+    $reconcileAuthoredState() {
+        return true;
+    }
+    $canRunAuthoredEffects() {
+        return this.$hydrated && this.$root !== null && this.$ready &&
+            !this.$deferredClientMount && this.isConnected;
+    }
     $flush(requireKnownState = this.$guardUnknownState === true) {
         if (!this.$ready || !this.$root) {
             this.$dirtyPaths = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/webui-framework",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "publishConfig": {
     "tag": "latest"
   },
@@ -43,7 +43,7 @@
     "dist/"
   ],
   "devDependencies": {
-    "@microsoft/webui-test-support": "0.0.29",
+    "@microsoft/webui-test-support": "0.0.30",
     "@playwright/test": "^1.63.0",
     "@types/node": "^26.5.1",
     "typescript": "7.0.2"