@microsoft/webui-framework 0.0.17 → 0.0.19

package/dist/decorators.d.ts

@@ -1,62 +1,12 @@
-/**
- * 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 declare function toKebabCase(str: string): string;
 export declare function getObservableNames(ctor: Function): Set<string>;
-/**
- * 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 declare function observable(target: object, name: string): void;
 export declare function isAttributeProperty(ctor: Function, property: string): boolean;
-/**
- * Like {@link observable} but also reflects to/from an HTML attribute
- * (kebab-case). The decorator patches `observedAttributes` and
- * `attributeChangedCallback` on the class so changes flow in both directions.
- *
- * @example
- * ```ts
- * class MyEl extends WebUIElement {
- *   @attr myProp = 'default';
- *   // syncs with attribute "my-prop"
- * }
- * ```
- */
+export declare function attributeNameForProperty(ctor: Function, property: string): string | undefined;
+export declare function syncAttrProperties(instance: object, ctor: Function): void;
+export declare function observable(target: object, name: string): void;
 export interface AttrOptions {
     attribute?: string;
-    /** When `'boolean'`, the property is `true` when the attribute is present
-     *  and `false` when absent — matching native HTML boolean attribute semantics.
-     *  Default is string mode (property receives the attribute string value). */
     mode?: 'boolean';
 }
-export declare function syncAttrProperties(instance: object, ctor: Function): void;
 export declare function attr(target: object, name: string): void;
 export declare function attr(options: AttrOptions): (target: object, name: string) => void;

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,100 @@ function attrPropertyMapFor(ctor) {
 export function isAttributeProperty(ctor, property) {
     return attrPropertyMapFor(ctor)?.has(property) === true;
 }
+export function attributeNameForProperty(ctor, property) {
+    return attrPropertyMapFor(ctor)?.get(property)?.attribute;
+}
+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 +197,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 +213,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 +231,6 @@ function applyAttr(target, name, options) {
                     ? newVal !== null
                     : newVal;
             }
-            // Preserve any pre-existing attributeChangedCallback.
             if (origACB) {
                 origACB.call(this, attribute, oldVal, newVal);
             }
@@ -304,15 +238,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,5 @@
-/**
- * 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. */
+import type { RepeatBinding, RepeatHost, RepeatKeyState } from './types.js';
 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 createRepeatKeyState(path: string): RepeatKeyState;
+export declare function seedHydratedRepeatKeys(rep: RepeatBinding, items: unknown[]): void;
 export declare function syncRepeat(host: RepeatHost, rep: RepeatBinding): void;