@microsoft/webui-framework 0.0.16 → 0.0.18

package/dist/decorators.js

@@ -1,23 +1,4 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-/**
- * Reactive decorators for WebUIElement properties.
- *
- * Uses TypeScript's `experimentalDecorators` emit, matching the FAST ecosystem
- * conventions.
- */
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-/**
- * Map of camelCase property names to their HTML attribute names.
- *
- * ARIA attributes (`ariaXxxYyy → aria-` + lowercase remainder) are handled
- * algorithmically in `toKebabCase`. Only HTML global/element attributes
- * with irregular mappings (concatenated lowercase) need explicit entries.
- */
 const propertyToAttribute = Object.assign(Object.create(null), {
-    // --- HTML global/element attributes ---
     accessKey: 'accesskey',
     autoCapitalize: 'autocapitalize',
     contentEditable: 'contenteditable',
@@ -40,41 +21,11 @@ const propertyToAttribute = Object.assign(Object.create(null), {
     tabIndex: 'tabindex',
     useMap: 'usemap',
 });
-/**
- * Convert a camelCase DOM property name into its kebab-case HTML attribute form.
- *
- * This function is optimized for framework-level hot paths where attribute
- * normalization may run thousands of times per render. It performs three
- * progressively cheaper checks:
- *
- * 1. **Direct lookup for irregular mappings**
- *    Many DOM properties (e.g., `readOnly`, `tabIndex`, `crossOrigin`) do not
- *    follow simple camelCase → kebab-case rules. These are resolved through a
- *    precomputed `propertyToAttribute` map for O(1) returns with no string
- *    processing.
- *
- * 2. **Fast path for ARIA attributes**
- *    ARIA properties always begin with `aria` followed by an uppercase letter
- *    (e.g., `ariaDescribedBy`). These map to `aria-` + the lowercase remainder.
- *    This branch avoids the general loop and uses the engine-optimized
- *    `.toLowerCase()` for the suffix.
- *
- * 3. **General camelCase → kebab-case conversion**
- *    For all other inputs, the function performs a tight ASCII-only scan:
- *    uppercase A–Z (65–90) are converted to lowercase and prefixed with `-`,
- *    while all other characters are copied as-is. This avoids regex engines,
- *    callback allocations, and match objects, producing predictable,
- *    allocation-minimal performance ideal for DOM attribute reflection.
- *
- * The result is a predictable, JIT-friendly transformation suitable for
- * attribute diffing, SSR serialization, and runtime DOM patching.
- */
 export function toKebabCase(str) {
     const mapped = propertyToAttribute[str];
     if (mapped)
         return mapped;
-    // ARIA properties: ariaXxxYyy → aria- + lowercase remainder
-    if (str.length > 4 && str.charCodeAt(0) === 97 /* a */ && str.startsWith('aria') && str.charCodeAt(4) >= 65 && str.charCodeAt(4) <= 90) {
+    if (str.length > 4 && str.charCodeAt(0) === 97 && str.startsWith('aria') && str.charCodeAt(4) >= 65 && str.charCodeAt(4) <= 90) {
         return 'aria-' + str.slice(4).toLowerCase();
     }
     let out = '';
@@ -85,96 +36,12 @@ export function toKebabCase(str) {
     return out;
 }
 const reflectingAttribute = Symbol('webui.reflectingAttribute');
+const EMPTY_SET = Object.freeze(new Set());
 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, {
-        get() {
-            return this[backingKey];
-        },
-        set(newValue) {
-            const oldValue = this[backingKey];
-            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);
-            }
-            if (this.isConnected) {
-                const upd = this['$update'];
-                if (upd)
-                    upd.call(this, name);
-            }
-        },
-        enumerable: true,
-        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
-// ---------------------------------------------------------------------------
-/** Per-class registry of @observable property names. */
 const observableRegistry = new WeakMap();
-/**
- * Get the set of @observable property names registered for a class.
- */
-const EMPTY_SET = Object.freeze(new Set());
 export function getObservableNames(ctor) {
     const names = observableRegistry.get(ctor);
     if (names)
@@ -192,26 +59,7 @@ function registerObservableProperty(ctor, name) {
     }
     names.add(name);
 }
-/**
- * Marks a property as observable. When the value changes the decorator will:
- * 1. Call `this.<prop>Changed(oldValue, newValue)` if defined.
- * 2. Call `this.$update(name)` if the element is connected, targeting
- *    only bindings that reference this property.
- */
-export function observable(target, name) {
-    const ctor = target.constructor;
-    registerObservableProperty(ctor, name);
-    createReactiveProperty(target, name);
-}
-// ---------------------------------------------------------------------------
-// @attr
-// ---------------------------------------------------------------------------
-/**
- * Registry of attribute-name → property-name mappings per constructor.
- * Used by `attributeChangedCallback` to route attribute changes to properties.
- */
 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);
@@ -246,6 +94,97 @@ function attrPropertyMapFor(ctor) {
 export function isAttributeProperty(ctor, property) {
     return attrPropertyMapFor(ctor)?.has(property) === true;
 }
+function setReflectingAttribute(instance, attrName) {
+    instance[reflectingAttribute] = attrName;
+}
+function restoreReflectingAttribute(instance) {
+    instance[reflectingAttribute] = undefined;
+}
+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);
+    }
+}
+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]);
+    }
+}
+function createReactiveProperty(proto, name, attrDefinition) {
+    const backingKey = `_${name}`;
+    const changedKey = `${name}Changed`;
+    Object.defineProperty(proto, name, {
+        get() {
+            return this[backingKey];
+        },
+        set(newValue) {
+            const oldValue = this[backingKey];
+            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);
+            }
+            if (this.isConnected) {
+                const upd = this['$update'];
+                if (upd)
+                    upd.call(this, name);
+            }
+        },
+        enumerable: true,
+        configurable: true,
+    });
+}
+export function observable(target, name) {
+    const ctor = target.constructor;
+    registerObservableProperty(ctor, name);
+    createReactiveProperty(target, name);
+}
 function applyAttr(target, name, options) {
     const proto = target;
     const ctor = proto.constructor;
@@ -255,11 +194,8 @@ function applyAttr(target, name, options) {
         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);
@@ -274,21 +210,17 @@ function applyAttr(target, name, options) {
         attrByProperty.set(ctor, byProperty);
     }
     byProperty.set(name, definition);
-    // 3. Accumulate observed attributes on the constructor.
     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() {
                 return ctor._observedAttrs ?? [];
             },
             configurable: true,
         });
-        // Patch `attributeChangedCallback` once per class.
         const origACB = proto['attributeChangedCallback'];
         proto['attributeChangedCallback'] = function (attribute, oldVal, newVal) {
-            // Route the attribute change to the corresponding property.
             const definition = attrDefinitionFor(this.constructor, attribute);
             if (definition !== undefined &&
                 this[reflectingAttribute] !== attribute) {
@@ -296,7 +228,6 @@ function applyAttr(target, name, options) {
                     ? newVal !== null
                     : newVal;
             }
-            // Preserve any pre-existing attributeChangedCallback.
             if (origACB) {
                 origACB.call(this, attribute, oldVal, newVal);
             }
@@ -304,15 +235,6 @@ 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/diff.d.ts

@@ -1,23 +1,3 @@
-/**
- * Keyed child reconciliation for `@for(item of items)` repeat blocks.
- *
- * Diff that matches old instances by key, reuses what it
- * can, creates/removes the rest, then reorders DOM nodes in one forward pass.
- */
 import type { RepeatBinding, RepeatHost } from './types.js';
-/** Resolve a dotted path from a start offset without allocating. */
 export declare function dotWalk(cursor: unknown, path: string, from: number): unknown;
-/**
- * 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 declare function resolveRepeatValue(scopeVar: string, scope: unknown, path: string): unknown;
-/**
- * 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 declare function syncRepeat(host: RepeatHost, rep: RepeatBinding): void;

package/dist/element/diff.js

@@ -1,16 +1,12 @@
-// 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,53 +15,27 @@ 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 };
 }
-// ── 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)
         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)
         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);
@@ -73,45 +43,40 @@ export function syncRepeat(host, rep) {
         rep.instances = [];
         return;
     }
-    const keyPath = Object.values(rep.attrMap)[0];
+    const keyPath = rep.keyPath;
     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
+        const oldLength = oldInstances.length;
+        const reuseCount = Math.min(oldLength, items.length);
+        let nextCount = reuseCount;
         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 });
+                oldInstances[nextCount] = { key: null, value: items[i], instance };
+                nextCount += 1;
             }
         }
-        // Remove excess old instances
-        for (let i = reuseCount; i < oldInstances.length; i += 1) {
+        for (let i = reuseCount; i < oldLength; i += 1) {
             host.$removeInstance(oldInstances[i].instance);
         }
-        rep.instances = next;
+        oldInstances.length = nextCount;
         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) {
+            cursor = host.$insertInstanceAfter(cursor, container, oldInstances[i].instance);
         }
         for (let i = 0; i < reuseCount; i += 1) {
-            host.$updateInstance(next[i].instance);
+            host.$updateInstance(oldInstances[i].instance);
         }
         return;
     }
-    // ── Keyed diff ─────────────────────────────────────────────────
-    // ── Build old-key → instance map ────────────────────────────────
     const oldByKey = new Map();
     for (let i = 0; i < oldInstances.length; i += 1) {
         const entry = oldInstances[i];
@@ -119,44 +84,42 @@ export function syncRepeat(host, rep) {
         if (k != null)
             oldByKey.set(k, entry);
     }
-    // ── Match / create ──────────────────────────────────────────────
-    const next = [];
+    let nextCount = 0;
     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);
+            oldByKey.set(key, undefined);
             existing.value = item;
             existing.key = key;
             if (existing.instance.scope)
                 existing.instance.scope.value = item;
-            next.push(existing);
+            oldInstances[nextCount] = existing;
+            nextCount += 1;
         }
         else {
             const scope = itemScope(rep, item);
             const instance = host.$createBlockInstance(rep.blockIndex, scope);
             if (instance) {
-                next.push({ key: key ?? null, value: item, instance });
+                oldInstances[nextCount] = { key: key ?? null, value: item, instance };
+                nextCount += 1;
             }
         }
     }
-    // ── Remove unmatched old instances ──────────────────────────────
     for (const leftover of oldByKey.values()) {
-        host.$removeInstance(leftover.instance);
+        if (leftover)
+            host.$removeInstance(leftover.instance);
     }
-    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.
+    oldInstances.length = nextCount;
     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) {
+        cursor = host.$insertInstanceAfter(cursor, container, oldInstances[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))
+        if (entry.key != null && oldByKey.has(entry.key) && oldByKey.get(entry.key) === undefined) {
             host.$updateInstance(entry.instance);
+        }
     }
 }

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;