@microsoft/webui-framework 0.0.17 → 0.0.18

package/dist/hydration-mismatch.d.ts

@@ -0,0 +1,22 @@
+import type { CompiledAttrPart } from './template.js';
+import { type AttrBinding, type CondBinding, type RepeatBinding, type ScopeFrame, type TextBinding } from './element/types.js';
+export interface MismatchContext {
+    resolver: (path: string, scope?: unknown) => unknown;
+    resolveParts: (parts: CompiledAttrPart[], scope?: ScopeFrame) => string;
+    resolveValue: (path: string, scope?: ScopeFrame) => unknown;
+}
+export interface PathBindings {
+    texts: TextBinding[];
+    attrs: AttrBinding[];
+    conds: CondBinding[];
+    repeats: RepeatBinding[];
+}
+export declare function reportHydrationMismatch(tag: string, writes: ReadonlySet<string>, index: ReadonlyMap<string, PathBindings>, ctx: MismatchContext): void;
+export declare function bindingsDisagreeWithDom(entry: PathBindings, ctx: MismatchContext): boolean;
+export declare function textDiffersFromDom(b: TextBinding, ctx: MismatchContext): boolean;
+export declare function attrDiffersFromDom(b: AttrBinding, ctx: MismatchContext): boolean;
+export declare function condDiffersFromDom(c: CondBinding, ctx: MismatchContext): boolean;
+export declare function repeatDiffersFromDom(r: RepeatBinding, ctx: MismatchContext): boolean;
+export declare function formatHydrationMismatch(tag: string, paths: string[]): string;
+export declare function warnHydrationMismatch(tag: string, paths: string[]): void;
+export declare function resetHydrationMismatchWarnings(): void;

package/dist/hydration-mismatch.js

@@ -0,0 +1,87 @@
+import { ATTR_KIND_BOOLEAN, ATTR_KIND_COMPLEX, ATTR_KIND_TEMPLATE, } from './element/types.js';
+export function reportHydrationMismatch(tag, writes, index, ctx) {
+    const mismatched = [];
+    for (const path of writes) {
+        const entry = index.get(path);
+        if (entry && bindingsDisagreeWithDom(entry, ctx))
+            mismatched.push(path);
+    }
+    if (mismatched.length !== 0)
+        warnHydrationMismatch(tag, mismatched);
+}
+export function bindingsDisagreeWithDom(entry, ctx) {
+    const { texts, attrs, conds, repeats } = entry;
+    for (let i = 0; i < texts.length; i++)
+        if (textDiffersFromDom(texts[i], ctx))
+            return true;
+    for (let i = 0; i < attrs.length; i++)
+        if (attrDiffersFromDom(attrs[i], ctx))
+            return true;
+    for (let i = 0; i < conds.length; i++)
+        if (condDiffersFromDom(conds[i], ctx))
+            return true;
+    for (let i = 0; i < repeats.length; i++)
+        if (repeatDiffersFromDom(repeats[i], ctx))
+            return true;
+    return false;
+}
+export function textDiffersFromDom(b, ctx) {
+    if (b.raw)
+        return false;
+    let expected;
+    if (b.parts) {
+        expected = ctx.resolveParts(b.parts, b.scope);
+    }
+    else if (b.path) {
+        const raw = ctx.resolveValue(b.path, b.scope);
+        expected = raw == null ? '' : String(raw);
+    }
+    else {
+        return false;
+    }
+    return b.node.data !== expected;
+}
+export function attrDiffersFromDom(b, ctx) {
+    const el = b.element;
+    switch (b.kind) {
+        case ATTR_KIND_COMPLEX:
+            return false;
+        case ATTR_KIND_BOOLEAN:
+            return el.hasAttribute(b.name) !== !!b.condition[0](ctx.resolver, b.scope);
+        case ATTR_KIND_TEMPLATE:
+            return (el.getAttribute(b.name) ?? '') !== ctx.resolveParts(b.parts, b.scope);
+        default: {
+            if (b.name === 'value' || b.name === 'checked' || b.name === 'selected')
+                return false;
+            const v = ctx.resolveValue(b.path, b.scope);
+            return (el.getAttribute(b.name) ?? '') !== (v == null ? '' : String(v));
+        }
+    }
+}
+export function condDiffersFromDom(c, ctx) {
+    return (c.instance != null) !== !!c.condition[0](ctx.resolver, c.scope);
+}
+export function repeatDiffersFromDom(r, ctx) {
+    const resolved = ctx.resolveValue(r.collection, r.scope);
+    const expectedLength = Array.isArray(resolved) ? resolved.length : 0;
+    return expectedLength !== r.instances.length;
+}
+export function formatHydrationMismatch(tag, paths) {
+    const list = paths.map((p) => `"${p}"`).join(', ');
+    return (`[WebUI] Hydration mismatch on <${tag}>: ` +
+        `${list} changed at or before super.connectedCallback() to a value that ` +
+        `differs from the server-rendered DOM. The DOM keeps the server value ` +
+        `(SSR content is trusted), so the element's state and DOM disagree. ` +
+        `Add the value to the SSR state, or assign it after super.connectedCallback().`);
+}
+const warnedMismatches = new Set();
+export function warnHydrationMismatch(tag, paths) {
+    const key = `${tag}\u0000${[...paths].sort().join('\u0000')}`;
+    if (warnedMismatches.has(key))
+        return;
+    warnedMismatches.add(key);
+    console.warn(formatHydrationMismatch(tag, paths));
+}
+export function resetHydrationMismatchWarnings() {
+    warnedMismatches.clear();
+}

package/dist/index.d.ts

@@ -1,22 +1,3 @@
-/**
- * @microsoft/webui-framework — lightweight Web Component runtime with SSR hydration.
- *
- * Provides a reactive base class, decorators, and hydration utilities for
- * building Web Components that work with WebUI's server-side rendering pipeline.
- *
- * @example
- * ```ts
- * import { WebUIElement, observable, attr } from '@microsoft/webui-framework';
- *
- * class MyCounter extends WebUIElement {
- *   @attr count = 0;
- *   @observable label = 'Count';
- * }
- * MyCounter.define('my-counter');
- * ```
- *
- * @packageDocumentation
- */
 export { WebUIElement } from './element.js';
 export { observable, attr } from './decorators.js';
 export { getTemplate, registerTemplateData } from './template.js';

package/dist/index.js

@@ -1,24 +1,5 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-/**
- * @microsoft/webui-framework — lightweight Web Component runtime with SSR hydration.
- *
- * Provides a reactive base class, decorators, and hydration utilities for
- * building Web Components that work with WebUI's server-side rendering pipeline.
- *
- * @example
- * ```ts
- * import { WebUIElement, observable, attr } from '@microsoft/webui-framework';
- *
- * class MyCounter extends WebUIElement {
- *   @attr count = 0;
- *   @observable label = 'Count';
- * }
- * MyCounter.define('my-counter');
- * ```
- *
- * @packageDocumentation
- */
+import { installTemplateElementRuntime } from './static-host.js';
+installTemplateElementRuntime();
 export { WebUIElement } from './element.js';
 export { observable, attr } from './decorators.js';
 export { getTemplate, registerTemplateData } from './template.js';

package/dist/lifecycle.d.ts

@@ -1,10 +1,2 @@
-/**
- * Call before a component begins hydration.
- * Increments the pending counter and (once) places the global start mark.
- */
 export declare function hydrationStart(): void;
-/**
- * Call after a component has finished hydration.
- * When the last component finishes, fires the global event + measure.
- */
 export declare function hydrationEnd(): void;

package/dist/lifecycle.js

@@ -1,34 +1,6 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-/**
- * Hydration lifecycle tracker.
- *
- * Tracks aggregate hydration timing via the Performance API and fires a
- * global `webui:hydration-complete` event on `window` once every registered
- * component has finished hydrating.
- *
- * ## Performance marks
- *
- * Global:
- * - `webui:hydrate:total:start`  — first component begins hydrating
- * - `webui:hydrate:total:end`    — last component finishes
- * - measure `webui:hydrate:total`
- *
- * ## Window event
- *
- * `webui:hydration-complete` — dispatched once on `window` when all
- * components are hydrated.
- */
-/** How many components are still waiting to hydrate. */
 let pendingCount = 0;
-/** Whether the global start mark has been placed. */
 let started = false;
-/** Whether the global complete event has already fired. */
 let completed = false;
-/**
- * Call before a component begins hydration.
- * Increments the pending counter and (once) places the global start mark.
- */
 export function hydrationStart() {
     if (!started) {
         performance.mark('webui:hydrate:total:start');
@@ -36,10 +8,6 @@ export function hydrationStart() {
     }
     pendingCount++;
 }
-/**
- * Call after a component has finished hydration.
- * When the last component finishes, fires the global event + measure.
- */
 export function hydrationEnd() {
     pendingCount--;
     if (pendingCount <= 0 && !completed) {

package/dist/static-host.d.ts

@@ -0,0 +1 @@
+export declare function installTemplateElementRuntime(): void;

package/dist/static-host.js

@@ -0,0 +1,58 @@
+import { TemplateElement } from './template-element.js';
+import { getTemplateRegistry } from './template.js';
+import { templateAttributeForRoot, templateNeedsStaticHost } from './template-roots.js';
+import { TEMPLATES_REGISTERED_EVENT, templateRegistrationDetail, } from './template-events.js';
+let runtimeInstalled = false;
+function defineTemplateHost(tag, meta) {
+    const w = window;
+    if (!w.__webui)
+        w.__webui = {};
+    if (!w.__webui.templates)
+        w.__webui.templates = {};
+    if (!w.__webui.templates[tag])
+        w.__webui.templates[tag] = meta;
+    class StaticTemplateHost extends TemplateElement {
+        $shouldApplyTemplateStateFromSSR(key) {
+            const attr = templateAttributeForRoot(meta, key);
+            return attr === undefined || !this.hasAttribute(attr);
+        }
+    }
+    StaticTemplateHost.define(tag);
+}
+function defineMissingTemplateHost(tag, meta) {
+    if (!templateNeedsStaticHost(meta) || customElements.get(tag))
+        return;
+    defineTemplateHost(tag, meta);
+}
+function defineTemplateHosts(templates = getTemplateRegistry()) {
+    if (!templates)
+        return;
+    const tags = Object.keys(templates);
+    for (let i = 0; i < tags.length; i++) {
+        const tag = tags[i];
+        const meta = templates[tag];
+        if (meta)
+            defineMissingTemplateHost(tag, meta);
+    }
+}
+export function installTemplateElementRuntime() {
+    if (runtimeInstalled) {
+        defineTemplateHosts();
+        return;
+    }
+    if (typeof window === 'undefined' || typeof document === 'undefined')
+        return;
+    runtimeInstalled = true;
+    window.addEventListener(TEMPLATES_REGISTERED_EVENT, (event) => {
+        const detail = templateRegistrationDetail(event);
+        if (!detail)
+            return;
+        if (detail.templates)
+            defineTemplateHosts(detail.templates);
+    });
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => defineTemplateHosts(), { once: true });
+        return;
+    }
+    defineTemplateHosts();
+}

package/dist/template-element.d.ts

@@ -0,0 +1,76 @@
+import type { TemplateBlockMeta, TemplateNodePath } from './template.js';
+import type { ScopeFrame, TemplateInstance } from './element/types.js';
+declare const WEBUI_SET_STATE_KEY: unique symbol;
+export declare class TemplateElement extends HTMLElement {
+    private $root;
+    private $meta?;
+    private $ready;
+    private $hydrated;
+    private $templateState;
+    private $dirtyPaths;
+    private $pendingFlush;
+    private $preReadyWrites;
+    private $resolver;
+    private $pathIndex?;
+    private $wildcardBindings?;
+    [WEBUI_SET_STATE_KEY](key: string, value: unknown): boolean;
+    static define(tagName: string): void;
+    connectedCallback(): void;
+    private $mount;
+    disconnectedCallback(): void;
+    $destroy(): void;
+    private $teardown;
+    private $teardownInstanceCleanups;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    setState(state: Record<string, unknown>): void;
+    protected $observableNames(): Set<string>;
+    protected $shouldApplySSRState(_key: string): boolean;
+    protected $syncAuthoredAttributes(): void;
+    protected $shouldApplyTemplateStateFromSSR(_key: string): boolean;
+    protected $setTemplateState(key: string, value: unknown): void;
+    private $writeTemplateState;
+    private $templateMeta;
+    private $templateRootForAttribute;
+    private $usesTemplateState;
+    private $setStateKey;
+    private $applySSRState;
+    $update(path?: string): void;
+    $flushUpdates(): void;
+    private $flush;
+    private $recordPreReadyWrite;
+    private $checkHydrationMismatch;
+    private $resolve;
+    private $resolveSSR;
+    private $parseTemplate;
+    private $createStagingRoot;
+    private $appendStagedChildren;
+    private $releaseStagingRepeatContainers;
+    private $wire;
+    private $hydrate;
+    private $collectBetween;
+    private $hydrateCondContent;
+    private $findMarker;
+    private $hasContentAfterMarker;
+    private $findSSRText;
+    private $findSSRSlotRef;
+    private $rootTag;
+    private $wireAttrs;
+    protected $finalize(_instance: TemplateInstance, _root: Node, _meta: TemplateBlockMeta, _resolver: (root: Node, path: TemplateNodePath) => Node | null, _scope?: ScopeFrame): void;
+    private $makeAttr;
+    private $repeatMaps;
+    private $buildPathIndex;
+    private $updateBindings;
+    $updateInstance(instance: TemplateInstance): void;
+    private $patchText;
+    private $patchAttr;
+    private $toggleCond;
+    $resolveValue(path: string, scope?: ScopeFrame): unknown;
+    private $resolveComponentRoot;
+    private $resolveParts;
+    $block(blockIndex: number): TemplateBlockMeta | undefined;
+    $createBlockInstance(blockIndex: number, scope?: ScopeFrame): TemplateInstance | null;
+    $removeInstance(instance: TemplateInstance): void;
+    $insertInstanceAfter(cursor: Node | null, container: ParentNode & Node, instance: TemplateInstance): Node | null;
+    private $singleDynamic;
+}
+export {};