@microsoft/webui-framework 0.0.5 → 0.0.7

package/dist/decorators.js

@@ -1,95 +1,137 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+/**
+ * Reactive decorators for WebUIElement properties.
+ *
+ * Uses legacy/experimental TypeScript decorators (`experimentalDecorators: true`)
+ * for compatibility with the FAST ecosystem conventions.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Convert camelCase to kebab-case for attribute reflection. */
 function toKebabCase(str) {
-  return str.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+    return str.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
 }
+/**
+ * Shared logic for installing a reactive getter/setter on a class prototype.
+ * The backing value is stored in a private `_prop` field on the instance.
+ */
 function createReactiveProperty(proto, name) {
-  const backingKey = `_${name}`;
-  const changedKey = `${name}Changed`;
-  Object.defineProperty(proto, name, {
-    get() {
-      return this[backingKey];
-    },
-    set(newValue) {
-      const oldValue = this[backingKey];
-      if (oldValue === newValue) return;
-      this[backingKey] = 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
-  });
+    const backingKey = `_${name}`;
+    const changedKey = `${name}Changed`;
+    Object.defineProperty(proto, name, {
+        get() {
+            return this[backingKey];
+        },
+        set(newValue) {
+            const oldValue = this[backingKey];
+            if (oldValue === newValue)
+                return;
+            this[backingKey] = 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,
+    });
 }
-const observableRegistry = /* @__PURE__ */ new WeakMap();
-const EMPTY_SET = Object.freeze(/* @__PURE__ */ new Set());
-function getObservableNames(ctor) {
-  return observableRegistry.get(ctor) ?? EMPTY_SET;
+// ---------------------------------------------------------------------------
+// @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) {
+    return observableRegistry.get(ctor) ?? EMPTY_SET;
 }
-function observable(target, name) {
-  const ctor = target.constructor;
-  if (!observableRegistry.has(ctor)) {
-    observableRegistry.set(ctor, /* @__PURE__ */ new Set());
-  }
-  observableRegistry.get(ctor).add(name);
-  createReactiveProperty(target, 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;
+    if (!observableRegistry.has(ctor)) {
+        observableRegistry.set(ctor, new Set());
+    }
+    observableRegistry.get(ctor).add(name);
+    createReactiveProperty(target, name);
 }
-const attrMap = /* @__PURE__ */ new WeakMap();
-const boolAttrs = /* @__PURE__ */ new WeakMap();
+// ---------------------------------------------------------------------------
+// @attr
+// ---------------------------------------------------------------------------
+/**
+ * Registry of attribute-name → property-name mappings per constructor.
+ * Used by `attributeChangedCallback` to route attribute changes to properties.
+ */
+const attrMap = new WeakMap();
+/** Registry of boolean-mode attribute names per constructor. */
+const boolAttrs = new WeakMap();
 function applyAttr(target, name, options) {
-  const proto = target;
-  const ctor = proto.constructor;
-  createReactiveProperty(proto, name);
-  const attrName = options?.attribute ?? toKebabCase(name);
-  if (!attrMap.has(ctor)) {
-    attrMap.set(ctor, /* @__PURE__ */ new Map());
-  }
-  attrMap.get(ctor).set(attrName, name);
-  if (options?.mode === "boolean") {
-    if (!boolAttrs.has(ctor)) {
-      boolAttrs.set(ctor, /* @__PURE__ */ new Set());
+    const proto = target;
+    const ctor = proto.constructor;
+    // 1. Install the reactive getter/setter (same as @observable).
+    createReactiveProperty(proto, name);
+    // 2. Register the attribute mapping.
+    const attrName = options?.attribute ?? toKebabCase(name);
+    if (!attrMap.has(ctor)) {
+        attrMap.set(ctor, new Map());
     }
-    boolAttrs.get(ctor).add(attrName);
-  }
-  if (!ctor._observedAttrs) {
-    ctor._observedAttrs = [];
-    Object.defineProperty(ctor, "observedAttributes", {
-      get() {
-        return ctor._observedAttrs ?? [];
-      },
-      configurable: true
-    });
-    const origACB = proto["attributeChangedCallback"];
-    proto["attributeChangedCallback"] = function(attribute, oldVal, newVal) {
-      const map = attrMap.get(this.constructor);
-      const propName = map?.get(attribute);
-      if (propName !== void 0) {
-        const isBool = boolAttrs.get(this.constructor)?.has(attribute);
-        this[propName] = isBool ? newVal !== null : newVal;
-      }
-      if (origACB) {
-        origACB.call(this, attribute, oldVal, newVal);
-      }
-    };
-  }
-  ctor._observedAttrs.push(attrName);
+    attrMap.get(ctor).set(attrName, name);
+    // Track boolean-mode attrs.
+    if (options?.mode === 'boolean') {
+        if (!boolAttrs.has(ctor)) {
+            boolAttrs.set(ctor, new Set());
+        }
+        boolAttrs.get(ctor).add(attrName);
+    }
+    // 3. Accumulate observed attributes on the constructor.
+    if (!ctor._observedAttrs) {
+        ctor._observedAttrs = [];
+        // 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 map = attrMap.get(this.constructor);
+            const propName = map?.get(attribute);
+            if (propName !== undefined) {
+                const isBool = boolAttrs.get(this.constructor)?.has(attribute);
+                this[propName] = isBool ? newVal !== null : newVal;
+            }
+            // Preserve any pre-existing attributeChangedCallback.
+            if (origACB) {
+                origACB.call(this, attribute, oldVal, newVal);
+            }
+        };
+    }
+    ctor._observedAttrs.push(attrName);
 }
-function attr(targetOrOptions, name) {
-  if (typeof name === "string") {
-    applyAttr(targetOrOptions, name);
-    return;
-  }
-  const options = targetOrOptions;
-  return (target, propName) => {
-    applyAttr(target, propName, options);
-  };
+export function attr(targetOrOptions, name) {
+    if (typeof name === 'string') {
+        applyAttr(targetOrOptions, name);
+        return;
+    }
+    const options = targetOrOptions;
+    return (target, propName) => {
+        applyAttr(target, propName, options);
+    };
 }
-export {
-  attr,
-  getObservableNames,
-  observable
-};

package/dist/element/diff.js

@@ -1,117 +1,160 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+// ── Helpers ─────────────────────────────────────────────────────────
 function asParent(node) {
-  if (!node) return null;
-  return "childNodes" in node ? node : null;
+    if (!node)
+        return null;
+    return 'childNodes' in node ? node : null;
 }
-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 (cursor == null || typeof cursor !== "object") return void 0;
-      cursor = cursor[path.slice(start, i)];
-      start = i + 1;
+/** 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 (cursor == null || typeof cursor !== 'object')
+                return undefined;
+            cursor = cursor[path.slice(start, i)];
+            start = i + 1;
+        }
     }
-  }
-  return cursor;
+    return cursor;
 }
-function resolveRepeatValue(scopeVar, scope, path) {
-  if (path === scopeVar) return scope;
-  if (!path.startsWith(`${scopeVar}.`)) return void 0;
-  return dotWalk(scope, path, scopeVar.length + 1);
+/**
+ * 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.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 === void 0 || keyPath === "") return null;
-  const v = dotWalk(item, keyPath, 0);
-  return v != null ? String(v) : "";
+    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 };
 }
-function syncRepeat(host, rep) {
-  const resolved = host.$resolveValue(rep.collection, rep.scope);
-  const items = Array.isArray(resolved) ? resolved : [];
-  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;
-  if (!rep.synced && items.length === 0 && rep.instances.length > 0) return;
-  rep.synced = true;
-  if (items.length === 0) {
-    for (let i = 0; i < rep.instances.length; i += 1) {
-      host.$removeInstance(rep.instances[i].instance);
+// ── 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);
+        }
+        rep.instances = [];
+        return;
     }
-    rep.instances = [];
-    return;
-  }
-  const keyPath = Object.values(rep.attrMap)[0];
-  const hasKeys = keyPath !== void 0 && keyPath !== "";
-  const oldInstances = rep.instances;
-  if (!hasKeys) {
-    const next2 = [];
-    const reuseCount = Math.min(oldInstances.length, items.length);
-    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];
-      next2.push(entry);
+    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 });
+            }
+        }
+        // Remove excess old instances
+        for (let i = reuseCount; i < oldInstances.length; i += 1) {
+            host.$removeInstance(oldInstances[i].instance);
+        }
+        rep.instances = next;
+        // Reorder + update
+        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 < next.length; i += 1) {
+            host.$updateInstance(next[i].instance);
+        }
+        return;
     }
-    for (let i = reuseCount; i < items.length; i += 1) {
-      const scope = itemScope(rep, items[i]);
-      const instance = host.$createBlockInstance(rep.blockIndex, scope);
-      if (instance) {
-        next2.push({ key: null, value: items[i], instance });
-      }
+    // ── 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);
     }
-    for (let i = reuseCount; i < oldInstances.length; i += 1) {
-      host.$removeInstance(oldInstances[i].instance);
+    // ── Match / create ──────────────────────────────────────────────
+    const next = [];
+    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);
+        }
+        else {
+            const scope = itemScope(rep, item);
+            const instance = host.$createBlockInstance(rep.blockIndex, scope);
+            if (instance) {
+                next.push({ key: key ?? null, value: item, instance });
+            }
+        }
     }
-    rep.instances = next2;
-    let cursor2 = rep.start;
-    for (let i = 0; i < next2.length; i += 1) {
-      cursor2 = host.$insertInstanceAfter(cursor2, container, next2[i].instance);
+    // ── Remove unmatched old instances ──────────────────────────────
+    for (const leftover of oldByKey.values()) {
+        host.$removeInstance(leftover.instance);
     }
-    for (let i = 0; i < next2.length; i += 1) {
-      host.$updateInstance(next2[i].instance);
+    rep.instances = next;
+    // ── Reorder DOM (forward pass) ──────────────────────────────────
+    // Walk forward, skip nodes already in position.
+    let cursor = rep.start;
+    for (let i = 0; i < next.length; i += 1) {
+        cursor = host.$insertInstanceAfter(cursor, container, next[i].instance);
     }
-    return;
-  }
-  const oldByKey = /* @__PURE__ */ 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);
-  }
-  const next = [];
-  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) : void 0;
-    if (existing) {
-      oldByKey.delete(key);
-      existing.value = item;
-      existing.key = key;
-      if (existing.instance.scope) existing.instance.scope.value = item;
-      next.push(existing);
-    } else {
-      const scope = itemScope(rep, item);
-      const instance = host.$createBlockInstance(rep.blockIndex, scope);
-      if (instance) {
-        next.push({ key: key ?? null, value: item, instance });
-      }
+    // ── Update bindings ─────────────────────────────────────────────
+    for (let i = 0; i < next.length; i += 1) {
+        host.$updateInstance(next[i].instance);
     }
-  }
-  for (const leftover of oldByKey.values()) {
-    host.$removeInstance(leftover.instance);
-  }
-  rep.instances = next;
-  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 < next.length; i += 1) {
-    host.$updateInstance(next[i].instance);
-  }
 }
-export {
-  dotWalk,
-  resolveRepeatValue,
-  syncRepeat
-};

package/dist/element/markers.d.ts

@@ -32,3 +32,23 @@ export declare function collectItemMarkers(repeatStart: Comment): {
  * 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;