@microsoft/webui-framework 0.0.28 → 0.0.30

package/README.md

@@ -12,10 +12,14 @@ 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
 
+Trusted Types support is automatic; no setup call is needed. To enforce it,
+allow the `webui` policy in CSP. See [Trusted Types](https://microsoft.github.io/webui/guide/concepts/hydration#trusted-types)
+for CSP requirements and raw-HTML limits.
+
 In this workspace:
 
 ```json
@@ -246,6 +250,20 @@ authored `<boundary>` directives through
 `@microsoft/webui-framework` entry has no dependency on the coordinator, so
 normal applications pay no streaming bundle or initialization cost.
 
+To keep the full application out of `<head>`, put the explicit
+`import '@microsoft/webui-framework/streaming.js'` in a small application-owned
+entry. Register that file with your bundler, preserve its side effect, and
+share framework modules with the application. Identify its output and static
+dependencies through native bundler metadata and your existing asset handoff.
+WebUI does not create entries, inject imports, or require a streaming manifest.
+
+Load the coordinator with `type="module" async`; marker-based deferral handles
+application-first delivery without a second framework bundle.
+The application may load later, but early-interactive components still need
+their registration modules. Use `fetchpriority="low"` on deferred authored
+module scripts to exclude them from automatic modulepreload hints. See
+[Separate coordinator and application assets](https://microsoft.github.io/webui/guide/concepts/hydration#separate-coordinator-and-application-assets).
+
 Boundaries may be authored in entries and reusable components, including
 runtime conditions, outlets, and selected routes. A boundary-bearing subtree
 reached from a `<for>` body fails the build with `boundary-in-repeat`. A whole
@@ -310,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/style-catalog.d.ts

@@ -0,0 +1,33 @@
+export type ComponentStyleResource = ({
+    kind: 'link';
+    href: string;
+} | {
+    kind: 'style';
+    css: string;
+} | {
+    kind: 'module';
+    specifier: string;
+    css: string;
+}) & {
+    members?: string[];
+};
+export interface ComponentStyles {
+    version: 1;
+    strategy: 'link' | 'style' | 'module';
+    resources: Record<string, ComponentStyleResource>;
+    closures: Record<string, string[]>;
+}
+export interface DocumentCatalog {
+    readonly resources: Map<string, ComponentStyleResource>;
+    readonly closures: Map<string, readonly string[]>;
+}
+export declare function catalogFor(document: Document): DocumentCatalog;
+export declare function sameComponentStyleResource(current: ComponentStyleResource, next: ComponentStyleResource): boolean;
+export declare function sameComponentStyleClosure(current: readonly string[], next: readonly string[]): boolean;
+export declare function prepareComponentStyles(value: unknown): ComponentStyles | undefined;
+export declare function requireComponentStyles(value: unknown): ComponentStyles;
+export declare function validateComponentStylesRegistration(styles: ComponentStyles | undefined, document?: Document): void;
+export declare function registerPreparedComponentStyles(styles: ComponentStyles, document?: Document): void;
+export declare function registerComponentStyles(value: ComponentStyles | unknown, document?: Document): void;
+export declare function hasRegisteredComponentStyleResource(id: string, document?: Document): boolean;
+export declare function hasComponentStyleWork(rootId: string, document?: Document): boolean;

package/dist/element/style-catalog.js

@@ -0,0 +1,154 @@
+const catalogs = new WeakMap();
+export function catalogFor(document) {
+    let catalog = catalogs.get(document);
+    if (!catalog) {
+        catalog = {
+            resources: new Map(),
+            closures: new Map(),
+        };
+        catalogs.set(document, catalog);
+    }
+    return catalog;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function sameComponentStyleResource(current, next) {
+    if (current === next)
+        return true;
+    const currentMembers = current.members;
+    const nextMembers = next.members;
+    if (currentMembers?.length !== nextMembers?.length ||
+        currentMembers?.some((member, index) => member !== nextMembers?.[index])) {
+        return false;
+    }
+    switch (current.kind) {
+        case 'link':
+            return next.kind === 'link' && current.href === next.href;
+        case 'style':
+            return next.kind === 'style' && current.css === next.css;
+        case 'module':
+            return next.kind === 'module' &&
+                current.specifier === next.specifier &&
+                current.css === next.css;
+    }
+}
+export function sameComponentStyleClosure(current, next) {
+    return current === next ||
+        (current.length === next.length && current.every((id, index) => id === next[index]));
+}
+export function prepareComponentStyles(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isObject(value) || value.version !== 1) {
+        throw new Error('[WebUI] componentStyles must use version 1.');
+    }
+    if (value.strategy !== 'link' && value.strategy !== 'style' && value.strategy !== 'module') {
+        throw new Error('[WebUI] componentStyles strategy must be "link", "style", or "module".');
+    }
+    if (!isObject(value.resources) || !isObject(value.closures)) {
+        throw new Error('[WebUI] componentStyles resources and closures must be objects.');
+    }
+    const strategy = value.strategy;
+    const resources = {};
+    for (const id of Object.keys(value.resources)) {
+        const resource = value.resources[id];
+        if (!id || !isObject(resource) || resource.kind !== strategy) {
+            throw new Error(`[WebUI] Invalid component style resource "${id}".`);
+        }
+        let members;
+        if (resource.members !== undefined) {
+            if (!Array.isArray(resource.members) ||
+                resource.members.length < 2 ||
+                resource.members.some(member => typeof member !== 'string' || !member) ||
+                new Set(resource.members).size !== resource.members.length) {
+                throw new Error(`[WebUI] Invalid component style resource members "${id}".`);
+            }
+            members = [...resource.members];
+        }
+        if (resource.kind === 'link' && typeof resource.href === 'string' && resource.href) {
+            resources[id] = members
+                ? { kind: 'link', href: resource.href, members }
+                : { kind: 'link', href: resource.href };
+        }
+        else if (resource.kind === 'style' && typeof resource.css === 'string') {
+            resources[id] = members
+                ? { kind: 'style', css: resource.css, members }
+                : { kind: 'style', css: resource.css };
+        }
+        else if (resource.kind === 'module' &&
+            typeof resource.specifier === 'string' && resource.specifier &&
+            typeof resource.css === 'string') {
+            resources[id] = members
+                ? { kind: 'module', specifier: resource.specifier, css: resource.css, members }
+                : { kind: 'module', specifier: resource.specifier, css: resource.css };
+        }
+        else {
+            throw new Error(`[WebUI] Invalid component style resource "${id}".`);
+        }
+    }
+    const closures = {};
+    for (const root of Object.keys(value.closures)) {
+        const closure = value.closures[root];
+        if (!root || !Array.isArray(closure)) {
+            throw new Error(`[WebUI] Invalid component style closure "${root}".`);
+        }
+        closures[root] = closure.map((id) => {
+            if (typeof id !== 'string' || !id) {
+                throw new Error(`[WebUI] Invalid resource ID in component style closure "${root}".`);
+            }
+            return id;
+        });
+    }
+    return { version: 1, strategy, resources, closures };
+}
+export function requireComponentStyles(value) {
+    const styles = prepareComponentStyles(value);
+    if (!styles) {
+        throw new Error('[WebUI] componentStyles is required.');
+    }
+    return styles;
+}
+export function validateComponentStylesRegistration(styles, document = globalThis.document) {
+    if (!styles)
+        return;
+    const catalog = catalogFor(document);
+    for (const id of Object.keys(styles.resources)) {
+        const current = catalog.resources.get(id);
+        if (current && !sameComponentStyleResource(current, styles.resources[id])) {
+            throw new Error(`[WebUI] Conflicting component style resource "${id}".`);
+        }
+    }
+    for (const root of Object.keys(styles.closures)) {
+        const current = catalog.closures.get(root);
+        const next = styles.closures[root];
+        if (current && !sameComponentStyleClosure(current, next)) {
+            throw new Error(`[WebUI] Conflicting component style closure "${root}".`);
+        }
+    }
+}
+export function registerPreparedComponentStyles(styles, document = globalThis.document) {
+    const catalog = catalogFor(document);
+    for (const id of Object.keys(styles.resources)) {
+        if (catalog.resources.has(id))
+            continue;
+        const resource = styles.resources[id];
+        catalog.resources.set(id, resource);
+    }
+    for (const root of Object.keys(styles.closures)) {
+        if (!catalog.closures.has(root)) {
+            catalog.closures.set(root, styles.closures[root]);
+        }
+    }
+}
+export function registerComponentStyles(value, document = globalThis.document) {
+    const styles = requireComponentStyles(value);
+    validateComponentStylesRegistration(styles, document);
+    registerPreparedComponentStyles(styles, document);
+}
+export function hasRegisteredComponentStyleResource(id, document = globalThis.document) {
+    return catalogFor(document).resources.has(id);
+}
+export function hasComponentStyleWork(rootId, document = globalThis.document) {
+    return (catalogFor(document).closures.get(rootId)?.length ?? 0) > 0;
+}

package/dist/element/styles.d.ts

@@ -1,39 +1,12 @@
-export type ComponentStyleResource = ({
-    kind: 'link';
-    href: string;
-} | {
-    kind: 'style';
-    css: string;
-} | {
-    kind: 'module';
-    specifier: string;
-    css: string;
-}) & {
-    members?: string[];
-};
-export interface ComponentStyles {
-    version: 1;
-    strategy: 'link' | 'style' | 'module';
-    resources: Record<string, ComponentStyleResource>;
-    closures: Record<string, string[]>;
-}
+export { hasComponentStyleWork, hasRegisteredComponentStyleResource, prepareComponentStyles, registerComponentStyles, registerPreparedComponentStyles, requireComponentStyles, sameComponentStyleClosure, sameComponentStyleResource, validateComponentStylesRegistration, } from './style-catalog.js';
+export type { ComponentStyleResource, ComponentStyles } from './style-catalog.js';
 type StyleTarget = Document | ShadowRoot;
 type CssModule = {
     default: CSSStyleSheet;
 };
 type CssModuleLoader = (specifier: string) => Promise<CssModule>;
 export declare function setCssModuleLoaderForTests(loader?: CssModuleLoader): void;
-export declare function sameComponentStyleResource(current: ComponentStyleResource, next: ComponentStyleResource): boolean;
-export declare function sameComponentStyleClosure(current: readonly string[], next: readonly string[]): boolean;
-export declare function prepareComponentStyles(value: unknown): ComponentStyles | undefined;
-export declare function requireComponentStyles(value: unknown): ComponentStyles;
-export declare function validateComponentStylesRegistration(styles: ComponentStyles | undefined, document?: Document): void;
-export declare function registerPreparedComponentStyles(styles: ComponentStyles, document?: Document): void;
-export declare function registerComponentStyles(value: ComponentStyles | unknown, document?: Document): void;
-export declare function hasRegisteredComponentStyleResource(id: string, document?: Document): boolean;
-export declare function hasComponentStyleWork(rootId: string, document?: Document): boolean;
 export declare function isComponentStyleMarker(element: Element): boolean;
 export declare function isComponentStyleResourceMarker(element: Element): boolean;
 export declare function claimSsrComponentStyles(source: Element, target: StyleTarget): void;
 export declare function installComponentStyles(rootId: string, target: StyleTarget, host?: HTMLElement): Promise<void> | undefined;
-export {};

package/dist/element/styles.js

@@ -1,6 +1,8 @@
 import { installComponentLinkStyles } from './link-styles.js';
+import { setImportMapContent } from '../trusted-types-policy.js';
+import { catalogFor } from './style-catalog.js';
+export { hasComponentStyleWork, hasRegisteredComponentStyleResource, prepareComponentStyles, registerComponentStyles, registerPreparedComponentStyles, requireComponentStyles, sameComponentStyleClosure, sameComponentStyleResource, validateComponentStylesRegistration, } from './style-catalog.js';
 const DEV = typeof __WEBUI_DEV__ === 'undefined' || __WEBUI_DEV__;
-const catalogs = new WeakMap();
 const installed = new WeakMap();
 const completedClosures = new WeakMap();
 const pending = new WeakMap();
@@ -14,26 +16,12 @@ let loadCssModule = defaultCssModuleLoader;
 export function setCssModuleLoaderForTests(loader) {
     loadCssModule = loader ?? defaultCssModuleLoader;
 }
-function catalogFor(document) {
-    let catalog = catalogs.get(document);
-    if (!catalog) {
-        catalog = {
-            resources: new Map(),
-            closures: new Map(),
-        };
-        catalogs.set(document, catalog);
-    }
-    return catalog;
-}
 function isDocument(target) {
     return target.nodeType === 9;
 }
 function owningDocument(target) {
     return isDocument(target) ? target : target.ownerDocument;
 }
-function isObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function styleGlobal(owner) {
     const configured = owner.defaultView?.__webui;
     if (configured || owner !== globalThis.document || typeof window === 'undefined') {
@@ -49,145 +37,6 @@ function readNonce(target = document) {
     const meta = owner.querySelector('meta[name="webui-nonce"]');
     return meta?.content ?? '';
 }
-export function sameComponentStyleResource(current, next) {
-    if (current === next)
-        return true;
-    const currentMembers = current.members;
-    const nextMembers = next.members;
-    if (currentMembers?.length !== nextMembers?.length ||
-        currentMembers?.some((member, index) => member !== nextMembers?.[index])) {
-        return false;
-    }
-    switch (current.kind) {
-        case 'link':
-            return next.kind === 'link' && current.href === next.href;
-        case 'style':
-            return next.kind === 'style' && current.css === next.css;
-        case 'module':
-            return next.kind === 'module' &&
-                current.specifier === next.specifier &&
-                current.css === next.css;
-    }
-}
-export function sameComponentStyleClosure(current, next) {
-    return current === next ||
-        (current.length === next.length && current.every((id, index) => id === next[index]));
-}
-export function prepareComponentStyles(value) {
-    if (value === undefined)
-        return undefined;
-    if (!isObject(value) || value.version !== 1) {
-        throw new Error('[WebUI] componentStyles must use version 1.');
-    }
-    if (value.strategy !== 'link' && value.strategy !== 'style' && value.strategy !== 'module') {
-        throw new Error('[WebUI] componentStyles strategy must be "link", "style", or "module".');
-    }
-    if (!isObject(value.resources) || !isObject(value.closures)) {
-        throw new Error('[WebUI] componentStyles resources and closures must be objects.');
-    }
-    const strategy = value.strategy;
-    const resources = {};
-    for (const id of Object.keys(value.resources)) {
-        const resource = value.resources[id];
-        if (!id || !isObject(resource) || resource.kind !== strategy) {
-            throw new Error(`[WebUI] Invalid component style resource "${id}".`);
-        }
-        let members;
-        if (resource.members !== undefined) {
-            if (!Array.isArray(resource.members) ||
-                resource.members.length < 2 ||
-                resource.members.some(member => typeof member !== 'string' || !member) ||
-                new Set(resource.members).size !== resource.members.length) {
-                throw new Error(`[WebUI] Invalid component style resource members "${id}".`);
-            }
-            members = [...resource.members];
-        }
-        if (resource.kind === 'link' && typeof resource.href === 'string' && resource.href) {
-            resources[id] = members
-                ? { kind: 'link', href: resource.href, members }
-                : { kind: 'link', href: resource.href };
-        }
-        else if (resource.kind === 'style' && typeof resource.css === 'string') {
-            resources[id] = members
-                ? { kind: 'style', css: resource.css, members }
-                : { kind: 'style', css: resource.css };
-        }
-        else if (resource.kind === 'module' &&
-            typeof resource.specifier === 'string' && resource.specifier &&
-            typeof resource.css === 'string') {
-            resources[id] = members
-                ? { kind: 'module', specifier: resource.specifier, css: resource.css, members }
-                : { kind: 'module', specifier: resource.specifier, css: resource.css };
-        }
-        else {
-            throw new Error(`[WebUI] Invalid component style resource "${id}".`);
-        }
-    }
-    const closures = {};
-    for (const root of Object.keys(value.closures)) {
-        const closure = value.closures[root];
-        if (!root || !Array.isArray(closure)) {
-            throw new Error(`[WebUI] Invalid component style closure "${root}".`);
-        }
-        closures[root] = closure.map((id) => {
-            if (typeof id !== 'string' || !id) {
-                throw new Error(`[WebUI] Invalid resource ID in component style closure "${root}".`);
-            }
-            return id;
-        });
-    }
-    return { version: 1, strategy, resources, closures };
-}
-export function requireComponentStyles(value) {
-    const styles = prepareComponentStyles(value);
-    if (!styles) {
-        throw new Error('[WebUI] componentStyles is required.');
-    }
-    return styles;
-}
-export function validateComponentStylesRegistration(styles, document = globalThis.document) {
-    if (!styles)
-        return;
-    const catalog = catalogFor(document);
-    for (const id of Object.keys(styles.resources)) {
-        const current = catalog.resources.get(id);
-        if (current && !sameComponentStyleResource(current, styles.resources[id])) {
-            throw new Error(`[WebUI] Conflicting component style resource "${id}".`);
-        }
-    }
-    for (const root of Object.keys(styles.closures)) {
-        const current = catalog.closures.get(root);
-        const next = styles.closures[root];
-        if (current && !sameComponentStyleClosure(current, next)) {
-            throw new Error(`[WebUI] Conflicting component style closure "${root}".`);
-        }
-    }
-}
-export function registerPreparedComponentStyles(styles, document = globalThis.document) {
-    const catalog = catalogFor(document);
-    for (const id of Object.keys(styles.resources)) {
-        if (catalog.resources.has(id))
-            continue;
-        const resource = styles.resources[id];
-        catalog.resources.set(id, resource);
-    }
-    for (const root of Object.keys(styles.closures)) {
-        if (!catalog.closures.has(root)) {
-            catalog.closures.set(root, styles.closures[root]);
-        }
-    }
-}
-export function registerComponentStyles(value, document = globalThis.document) {
-    const styles = requireComponentStyles(value);
-    validateComponentStylesRegistration(styles, document);
-    registerPreparedComponentStyles(styles, document);
-}
-export function hasRegisteredComponentStyleResource(id, document = globalThis.document) {
-    return catalogFor(document).resources.has(id);
-}
-export function hasComponentStyleWork(rootId, document = globalThis.document) {
-    return (catalogFor(document).closures.get(rootId)?.length ?? 0) > 0;
-}
 function targetInstalledResources(target) {
     let targetInstalled = installed.get(target);
     if (!targetInstalled) {
@@ -362,9 +211,7 @@ function installModuleImportMap(target, specifier, css) {
     const nonce = readNonce(target);
     if (nonce)
         script.nonce = nonce;
-    script.textContent = JSON.stringify({
-        imports: { [specifier]: `data:text/css,${encodeURIComponent(css)}` },
-    });
+    setImportMapContent(script, specifier, css, owner.defaultView);
     owner.head.appendChild(script);
     installedSpecifiers.add(specifier);
 }

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;