@microsoft/webui-framework 0.0.17 → 0.0.19

package/dist/element/diff.js

@@ -1,16 +1,7 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-// ── Helpers ─────────────────────────────────────────────────────────
-function asParent(node) {
-    if (!node)
-        return null;
-    return 'childNodes' in node ? node : null;
-}
-/** Resolve a dotted path from a start offset without allocating. */
 export function dotWalk(cursor, path, from) {
     let start = from;
     for (let i = from; i <= path.length; i++) {
-        if (i === path.length || path.charCodeAt(i) === 46 /* . */) {
+        if (i === path.length || path.charCodeAt(i) === 46) {
             if (cursor == null || typeof cursor !== 'object')
                 return undefined;
             cursor = cursor[path.slice(start, i)];
@@ -19,144 +10,223 @@ export function dotWalk(cursor, path, from) {
     }
     return cursor;
 }
-/**
- * Resolve a dotted path against a repeat scope variable.
- *
- * When a binding inside `@for(item of items)` references `item.title`,
- * this function looks up `title` on the current scope value.
- */
-export function resolveRepeatValue(scopeVar, scope, path) {
-    if (path === scopeVar)
-        return scope;
-    if (path.length <= scopeVar.length || path.charCodeAt(scopeVar.length) !== 46 /* '.' */ || !path.startsWith(scopeVar))
-        return undefined;
-    return dotWalk(scope, path, scopeVar.length + 1);
-}
-/** Compute a key for an item using the cached key path, or null. */
-function itemKey(item, keyPath) {
-    if (keyPath === undefined || keyPath === '')
-        return null;
-    const v = dotWalk(item, keyPath, 0);
-    return v != null ? String(v) : '';
-}
-/** Build a scope frame for a repeat item. */
 function itemScope(rep, item) {
-    return { name: rep.itemVar, value: item, parent: rep.scope };
+    return { name: rep.itemVar, value: item, parent: rep.scope, known: true };
 }
-// ── Reconciliation ──────────────────────────────────────────────────
-/**
- * Reconcile a repeat binding against its current collection value.
- *
- * Called by `$updateInstance` on every reactive update.  Resolves the
- * collection path, diffs old vs. new items by key, and patches the DOM.
- */
-export function syncRepeat(host, rep) {
-    const resolved = host.$resolveValue(rep.collection, rep.scope);
-    const items = Array.isArray(resolved) ? resolved : [];
-    // Locate the container once and cache it.
-    let container = rep.container
-        ?? (rep.start ? asParent(rep.start.parentNode) : null)
-        ?? (rep.owner.nodes[0] ? asParent(rep.owner.nodes[0].parentNode) : null);
-    if (!container)
+export function createRepeatKeyState(path) {
+    return {
+        path,
+        warned: false,
+        keys: [],
+        nextKeys: [],
+        map: new Map(),
+    };
+}
+export function seedHydratedRepeatKeys(rep, items) {
+    const state = rep.keyState;
+    if (!state || items.length !== rep.instances.length)
         return;
-    rep.container = container;
-    // Before the first client-side sync, bail if the collection hasn't
-    // been explicitly set but SSR children already exist.
-    if (!rep.synced && items.length === 0 && rep.instances.length > 0)
+    if (!collectRepeatKeys(items, state))
         return;
-    rep.synced = true;
-    // If there are no items, just tear down everything.
-    if (items.length === 0) {
-        for (let i = 0; i < rep.instances.length; i += 1) {
-            host.$removeInstance(rep.instances[i].instance);
-        }
-        rep.instances = [];
+    commitKeyIdentity(state);
+}
+function setItemScope(instance, item) {
+    if (!instance.scope)
         return;
+    instance.scope.value = item;
+    instance.scope.known = true;
+}
+function syncPositional(host, rep, items, container) {
+    const instances = rep.instances;
+    const oldLength = instances.length;
+    const reuseCount = Math.min(oldLength, items.length);
+    let nextCount = reuseCount;
+    let created = false;
+    for (let i = 0; i < reuseCount; i += 1) {
+        setItemScope(instances[i], items[i]);
     }
-    const keyPath = Object.values(rep.attrMap)[0];
-    const hasKeys = keyPath !== undefined && keyPath !== '';
-    const oldInstances = rep.instances;
-    // ── Fast path for unkeyed (index-based) repeats ────────────────
-    if (!hasKeys) {
-        const next = [];
-        const reuseCount = Math.min(oldInstances.length, items.length);
-        // Reuse existing instances by index
-        for (let i = 0; i < reuseCount; i += 1) {
-            const entry = oldInstances[i];
-            entry.value = items[i];
-            if (entry.instance.scope)
-                entry.instance.scope.value = items[i];
-            next.push(entry);
-        }
-        // Create new instances for items beyond old length
-        for (let i = reuseCount; i < items.length; i += 1) {
-            const scope = itemScope(rep, items[i]);
-            const instance = host.$createBlockInstance(rep.blockIndex, scope);
-            if (instance) {
-                next.push({ key: null, value: items[i], instance });
-            }
+    for (let i = reuseCount; i < items.length; i += 1) {
+        const instance = host.$createBlockInstance(rep.blockIndex, itemScope(rep, items[i]), rep.owner, container);
+        if (instance) {
+            instances[nextCount] = instance;
+            nextCount += 1;
+            created = true;
         }
-        // Remove excess old instances
-        for (let i = reuseCount; i < oldInstances.length; i += 1) {
-            host.$removeInstance(oldInstances[i].instance);
+    }
+    for (let i = reuseCount; i < oldLength; i += 1) {
+        host.$removeInstance(instances[i]);
+    }
+    instances.length = nextCount;
+    const removed = oldLength > reuseCount;
+    let cursor = rep.start;
+    for (let i = 0; i < instances.length; i += 1) {
+        cursor = host.$insertInstanceAfter(cursor, container, instances[i]);
+    }
+    for (let i = 0; i < reuseCount; i += 1) {
+        host.$updateInstance(instances[i]);
+    }
+    if (created || removed)
+        host.$changeStructure(removed ? rep.owner : undefined);
+}
+function readRepeatKey(item, path) {
+    if (path.length === 0)
+        return item;
+    return dotWalk(item, path, 0);
+}
+function isRepeatKey(value) {
+    return (typeof value === 'string' ||
+        (typeof value === 'number' && Number.isFinite(value)));
+}
+function collectRepeatKeys(items, state) {
+    const keys = state.nextKeys;
+    const seen = state.map;
+    keys.length = items.length;
+    seen.clear();
+    for (let i = 0; i < items.length; i += 1) {
+        let value;
+        try {
+            value = readRepeatKey(items[i], state.path);
         }
-        rep.instances = next;
-        let cursor = rep.start;
-        for (let i = 0; i < next.length; i += 1) {
-            cursor = host.$insertInstanceAfter(cursor, container, next[i].instance);
+        catch {
+            keys.length = 0;
+            seen.clear();
+            return false;
         }
-        for (let i = 0; i < reuseCount; i += 1) {
-            host.$updateInstance(next[i].instance);
+        if (!isRepeatKey(value) || seen.has(value)) {
+            keys.length = 0;
+            seen.clear();
+            return false;
         }
-        return;
+        keys[i] = value;
+        seen.set(value, null);
     }
-    // ── Keyed diff ─────────────────────────────────────────────────
-    // ── Build old-key → instance map ────────────────────────────────
-    const oldByKey = new Map();
-    for (let i = 0; i < oldInstances.length; i += 1) {
-        const entry = oldInstances[i];
-        const k = entry.key;
-        if (k != null)
-            oldByKey.set(k, entry);
-    }
-    // ── Match / create ──────────────────────────────────────────────
-    const next = [];
+    seen.clear();
+    return true;
+}
+function commitKeyIdentity(state) {
+    const oldKeys = state.keys;
+    state.keys = state.nextKeys;
+    state.nextKeys = oldKeys;
+    state.nextKeys.length = 0;
+}
+function clearKeyIdentity(state) {
+    state.keys.length = 0;
+    state.nextKeys.length = 0;
+    state.map.clear();
+}
+function warnKeyFallback(rep, state) {
+    if (state.warned)
+        return;
+    state.warned = true;
+    const key = state.path.length === 0
+        ? rep.itemVar
+        : `${rep.itemVar}.${state.path}`;
+    console.warn(`[webui] repeat "${rep.collection}" produced duplicate or invalid values for child key="${key}"; using positional reconciliation`);
+}
+function reconcileByKey(host, rep, items, container, state) {
+    const instances = rep.instances;
+    const map = state.map;
+    let nextCount = 0;
+    let created = false;
+    let removed = false;
     for (let i = 0; i < items.length; i += 1) {
-        const item = items[i];
-        const key = itemKey(item, keyPath);
-        const existing = key != null ? oldByKey.get(key) : undefined;
-        if (existing) {
-            oldByKey.delete(key);
-            existing.value = item;
-            existing.key = key;
-            if (existing.instance.scope)
-                existing.instance.scope.value = item;
-            next.push(existing);
+        const key = state.nextKeys[i];
+        let instance = map.get(key);
+        if (instance) {
+            map.set(key, null);
+            setItemScope(instance, items[i]);
         }
         else {
-            const scope = itemScope(rep, item);
-            const instance = host.$createBlockInstance(rep.blockIndex, scope);
-            if (instance) {
-                next.push({ key: key ?? null, value: item, instance });
-            }
+            instance = host.$createBlockInstance(rep.blockIndex, itemScope(rep, items[i]), rep.owner, container) ?? undefined;
+            if (instance)
+                created = true;
+        }
+        if (instance) {
+            instances[nextCount] = instance;
+            state.nextKeys[nextCount] = key;
+            nextCount += 1;
         }
     }
-    // ── Remove unmatched old instances ──────────────────────────────
-    for (const leftover of oldByKey.values()) {
-        host.$removeInstance(leftover.instance);
+    state.nextKeys.length = nextCount;
+    for (const instance of map.values()) {
+        if (instance) {
+            host.$removeInstance(instance);
+            removed = true;
+        }
     }
-    rep.instances = next;
-    // ── Reorder DOM (forward pass) ──────────────────────────────────
-    // Newly-created instances were patched while detached. Reused instances
-    // update after moving so nested structural nodes stay with the item.
     let cursor = rep.start;
-    for (let i = 0; i < next.length; i += 1) {
-        cursor = host.$insertInstanceAfter(cursor, container, next[i].instance);
-    }
-    for (let i = 0; i < oldInstances.length; i += 1) {
-        const entry = oldInstances[i];
-        const k = entry.key;
-        if (k != null && !oldByKey.has(k))
-            host.$updateInstance(entry.instance);
+    for (let i = 0; i < nextCount; i += 1) {
+        cursor = host.$insertInstanceAfter(cursor, container, instances[i]);
+    }
+    for (let i = 0; i < nextCount; i += 1) {
+        if (map.get(state.nextKeys[i]) === null) {
+            host.$updateInstance(instances[i]);
+        }
+    }
+    map.clear();
+    instances.length = nextCount;
+    commitKeyIdentity(state);
+    if (created || removed)
+        host.$changeStructure(removed ? rep.owner : undefined);
+}
+function syncKeyed(host, rep, items, container, state) {
+    if (!collectRepeatKeys(items, state)) {
+        warnKeyFallback(rep, state);
+        clearKeyIdentity(state);
+        syncPositional(host, rep, items, container);
+        return;
+    }
+    let sharedOrder = true;
+    const sharedLength = Math.min(state.keys.length, state.nextKeys.length);
+    for (let i = 0; sharedOrder && i < sharedLength; i += 1) {
+        sharedOrder = state.keys[i] === state.nextKeys[i];
+    }
+    if (state.keys.length !== rep.instances.length || sharedOrder) {
+        syncPositional(host, rep, items, container);
+        if (rep.instances.length === items.length) {
+            commitKeyIdentity(state);
+        }
+        else {
+            clearKeyIdentity(state);
+        }
+        return;
+    }
+    for (let i = 0; i < state.keys.length; i += 1) {
+        state.map.set(state.keys[i], rep.instances[i]);
+    }
+    reconcileByKey(host, rep, items, container, state);
+}
+export function syncRepeat(host, rep) {
+    const resolved = host.$resolveValue(rep.collection, rep.scope);
+    const items = Array.isArray(resolved) ? resolved : [];
+    const container = (rep.container
+        ?? rep.start?.parentNode
+        ?? rep.owner.nodes[0]?.parentNode);
+    if (!container)
+        return;
+    rep.container = container;
+    if (!rep.synced
+        && rep.instances.length > 0
+        && !host.$hasStateRoot(rep.collection, rep.scope))
+        return;
+    rep.synced = true;
+    if (items.length === 0) {
+        const hadInstances = rep.instances.length !== 0;
+        for (let i = 0; i < rep.instances.length; i += 1) {
+            host.$removeInstance(rep.instances[i]);
+        }
+        rep.instances.length = 0;
+        if (hadInstances)
+            host.$changeStructure(rep.owner);
+        if (rep.keyState) {
+            clearKeyIdentity(rep.keyState);
+        }
+        return;
+    }
+    if (rep.keyState) {
+        syncKeyed(host, rep, items, container, rep.keyState);
+    }
+    else {
+        syncPositional(host, rep, items, container);
     }
 }

package/dist/element/markers.d.ts

@@ -1,54 +1,10 @@
-/**
- * Hydration marker utilities for zero-DOM-mutation in-place hydration.
- *
- * The WebUI handler plugin emits lightweight HTML comment markers around
- * structural boundaries (for-loops and if-conditions). These utilities
- * walk markers and locate elements so the hydration path can wire
- * bindings in-place without reparenting DOM nodes.
- *
- * Marker format:
- *   <!--wr-->   repeat block start
- *   <!--/wr-->  repeat block end
- *   <!--wi-->   repeat item boundary
- *   <!--wc-->   conditional block start
- *   <!--/wc-->  conditional block end
- */
 export declare const MARKER_REPEAT_START = "wr";
 export declare const MARKER_REPEAT_END = "/wr";
 export declare const MARKER_COND_START = "wc";
 export declare const MARKER_COND_END = "/wc";
-/**
- * Collect the item markers (<!--wi-->) within a repeat range.
- *
- * Walks siblings from the repeat start marker to the repeat end marker.
- * Returns an array of <!--wi--> comment nodes that delineate items.
- */
 export declare function collectItemMarkers(repeatStart: Comment): {
     items: Comment[];
     end: Comment | null;
 };
-/**
- * Get the next element sibling after a marker comment, skipping
- * whitespace text nodes and other comments.
- */
 export declare function nextElement(marker: Comment): Element | null;
-/**
- * Find the Nth child of a given nodeType, skipping structural block ranges.
- *
- * The compiled template static HTML (`meta.h`) does not contain conditional
- * or repeat block content — those are stored as separate block metadata.
- * But the SSR DOM has this content rendered inline between marker pairs
- * (`<!--wc-->...<!--/wc-->` and `<!--wr-->...<!--/wr-->`).
- *
- * This function walks `parent.firstChild` → siblings, counting only
- * children of the requested `nodeType` that are NOT inside a structural
- * block range.  Nested blocks of the same type are handled via depth
- * tracking.  Returns the child at the given `ordinal`, or null.
- *
- * Used by `$resolveSSR` (element ordinals) and `$findSSRText` (text
- * ordinals) to keep SSR DOM ordinals aligned with template metadata.
- *
- * **Requires closing markers to still be in the DOM** — caller must
- * not remove `<!--/wc-->` or `<!--/wr-->` before all resolution is done.
- */
 export declare function findByOrdinal(parent: Node, nodeType: number, ordinal: number): Node | null;

package/dist/element/markers.js

@@ -1,100 +1,60 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-/**
- * Hydration marker utilities for zero-DOM-mutation in-place hydration.
- *
- * The WebUI handler plugin emits lightweight HTML comment markers around
- * structural boundaries (for-loops and if-conditions). These utilities
- * walk markers and locate elements so the hydration path can wire
- * bindings in-place without reparenting DOM nodes.
- *
- * Marker format:
- *   <!--wr-->   repeat block start
- *   <!--/wr-->  repeat block end
- *   <!--wi-->   repeat item boundary
- *   <!--wc-->   conditional block start
- *   <!--/wc-->  conditional block end
- */
-// Marker data constants matching the handler plugin output.
 export const MARKER_REPEAT_START = 'wr';
 export const MARKER_REPEAT_END = '/wr';
 export const MARKER_COND_START = 'wc';
 export const MARKER_COND_END = '/wc';
 const MARKER_REPEAT_ITEM = 'wi';
-/**
- * Collect the item markers (<!--wi-->) within a repeat range.
- *
- * Walks siblings from the repeat start marker to the repeat end marker.
- * Returns an array of <!--wi--> comment nodes that delineate items.
- */
 export function collectItemMarkers(repeatStart) {
     const items = [];
     let end = null;
+    let depth = 1;
     let node = repeatStart.nextSibling;
     while (node) {
-        if (node.nodeType === 8 /* COMMENT_NODE */) {
+        if (node.nodeType === 8) {
             const data = node.data;
-            if (data === MARKER_REPEAT_END) {
-                end = node;
-                break;
+            if (data === MARKER_REPEAT_START) {
+                depth++;
             }
-            if (data === MARKER_REPEAT_ITEM)
+            else if (data === MARKER_REPEAT_END) {
+                depth--;
+                if (depth === 0) {
+                    end = node;
+                    break;
+                }
+            }
+            else if (data === MARKER_REPEAT_ITEM && depth === 1) {
                 items.push(node);
+            }
         }
         node = node.nextSibling;
     }
     return { items, end };
 }
-/**
- * Get the next element sibling after a marker comment, skipping
- * whitespace text nodes and other comments.
- */
 export function nextElement(marker) {
     let node = marker.nextSibling;
     while (node) {
-        if (node.nodeType === 1 /* ELEMENT_NODE */)
+        if (node.nodeType === 1)
             return node;
-        if (node.nodeType === 8 /* COMMENT_NODE */) {
+        if (node.nodeType === 8) {
             const data = node.data;
-            if (data === MARKER_REPEAT_END || data === MARKER_REPEAT_ITEM)
+            if (data === MARKER_REPEAT_END || data === MARKER_REPEAT_ITEM || data === MARKER_COND_END)
                 return null;
         }
         node = node.nextSibling;
     }
     return null;
 }
-/**
- * Find the Nth child of a given nodeType, skipping structural block ranges.
- *
- * The compiled template static HTML (`meta.h`) does not contain conditional
- * or repeat block content — those are stored as separate block metadata.
- * But the SSR DOM has this content rendered inline between marker pairs
- * (`<!--wc-->...<!--/wc-->` and `<!--wr-->...<!--/wr-->`).
- *
- * This function walks `parent.firstChild` → siblings, counting only
- * children of the requested `nodeType` that are NOT inside a structural
- * block range.  Nested blocks of the same type are handled via depth
- * tracking.  Returns the child at the given `ordinal`, or null.
- *
- * Used by `$resolveSSR` (element ordinals) and `$findSSRText` (text
- * ordinals) to keep SSR DOM ordinals aligned with template metadata.
- *
- * **Requires closing markers to still be in the DOM** — caller must
- * not remove `<!--/wc-->` or `<!--/wr-->` before all resolution is done.
- */
 export function findByOrdinal(parent, nodeType, ordinal) {
     let count = 0;
     let child = parent.firstChild;
     while (child) {
-        // Detect a structural block opening marker and skip the entire range.
-        if (child.nodeType === 8 /* COMMENT_NODE */) {
+        if (child.nodeType === 8) {
             const data = child.data;
             if (data === MARKER_COND_START || data === MARKER_REPEAT_START) {
                 const endTag = data === MARKER_COND_START ? MARKER_COND_END : MARKER_REPEAT_END;
                 let depth = 1;
                 child = child.nextSibling;
                 while (child && depth > 0) {
-                    if (child.nodeType === 8 /* COMMENT_NODE */) {
+                    if (child.nodeType === 8) {
                         const d = child.data;
                         if (d === data)
                             depth++;
@@ -104,7 +64,6 @@ export function findByOrdinal(parent, nodeType, ordinal) {
                     if (depth > 0)
                         child = child.nextSibling;
                 }
-                // Advance past the closing marker itself
                 if (child)
                     child = child.nextSibling;
                 continue;

package/dist/element/styles.d.ts

@@ -1,11 +1 @@
-/**
- * Adopt a CSS module stylesheet onto a shadow root, or inject into `<head>`
- * for light DOM components.
- *
- * For shadow DOM: uses `import(specifier, { with: { type: "css" } })` to
- * retrieve the browser-registered CSSStyleSheet from the module registry.
- * The browser caches the sheet internally — no application-level cache needed.
- *
- * For light DOM: appends a `<style>` element to `<head>` (once per specifier).
- */
 export declare function injectModuleStyle(specifier: string, shadowRoot: ShadowRoot | null): void;

package/dist/element/styles.js

@@ -1,78 +1,17 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-/**
- * Stylesheet management for WebUI components.
- *
- * Three CSS strategies are supported:
- *
- * - **Link**: `<link rel="stylesheet">` tags in each component's shadow template.
- *   The browser deduplicates fetches by URL. No JS-side style management needed.
- *
- * - **Style**: Inline `<style>` tags inside each shadow template.
- *
- * - **Module**: Uses CSS Modules registered via Import Maps. During SSR, the
- *   handler emits a `<script type="importmap">{"imports":{"<tag>":"data:text/css,..."}}</script>`
- *   in each rendered component's light DOM. The browser registers the
- *   stylesheet globally under `<tag>` and automatically adopts it via
- *   `shadowrootadoptedstylesheets` on declarative shadow roots.
- *
- *   During SPA navigation, the router appends new importmap script tags to
- *   `<head>` via `templateStyles[]`. The framework uses
- *   `import(specifier, { with: { type: "css" } })` to retrieve the browser's
- *   registered CSSStyleSheet and adopts it onto the shadow root. This is a
- *   direct hash-map lookup in the browser's module registry - no DOM queries,
- *   no manual CSSStyleSheet construction.
- *
- * For light DOM components (no shadow root), Module mode injects a `<style>`
- * element in `<head>`, deduplicated by `headInjected`.
- */
-/**
- * Specifiers already injected into `<head>` via the light DOM path.
- * Prevents duplicate `<style>` elements for non-shadow components.
- */
 const headInjected = new Set();
-/**
- * Adopt a CSS module stylesheet onto a shadow root, or inject into `<head>`
- * for light DOM components.
- *
- * For shadow DOM: uses `import(specifier, { with: { type: "css" } })` to
- * retrieve the browser-registered CSSStyleSheet from the module registry.
- * The browser caches the sheet internally — no application-level cache needed.
- *
- * For light DOM: appends a `<style>` element to `<head>` (once per specifier).
- */
 export function injectModuleStyle(specifier, shadowRoot) {
     if (shadowRoot) {
-        // SSR hydration: the browser already adopted the sheet from
-        // shadowrootadoptedstylesheets on the declarative shadow root.
         if (shadowRoot.adoptedStyleSheets.length > 0)
             return;
-        // SPA path: import the CSS module from the browser's registry.
-        // The specifier was registered via a `<script type="importmap">` tag
-        // (either inlined at SSR time or appended to <head> by the router during
-        // partial navigation). The import resolves to the same CSSStyleSheet the
-        // browser registered.
         import(specifier, { with: { type: 'css' } }).then((mod) => {
-            shadowRoot.adoptedStyleSheets = [
-                ...shadowRoot.adoptedStyleSheets,
-                mod.default,
-            ];
+            shadowRoot.adoptedStyleSheets.push(mod.default);
         }, () => {
-            // Specifier not registered — component has no CSS module definition.
-            // This is expected for Link/Style strategies or components without CSS.
         });
     }
     else if (!headInjected.has(specifier)) {
         headInjected.add(specifier);
         import(specifier, { with: { type: 'css' } }).then((mod) => {
-            const style = document.createElement('style');
-            const rules = mod.default.cssRules;
-            let cssText = '';
-            for (let i = 0; i < rules.length; i++) {
-                cssText += rules[i].cssText;
-            }
-            style.textContent = cssText;
-            document.head.appendChild(style);
+            document.adoptedStyleSheets.push(mod.default);
         }, () => { });
     }
 }