@microsoft/webui-framework 0.0.17 → 0.0.19

package/dist/element/types.d.ts

@@ -1,41 +1,17 @@
-/**
- * Shared runtime types for the WebUI element system.
- *
- * These types define the binding data structures that are created once during
- * hydration and then read on every reactive update.  Each binding holds a
- * direct DOM node reference so that updates can patch the DOM in O(1) per
- * binding without any tree walking or selector queries.
- *
- * ## Key concepts
- *
- * - **TemplateInstance** — a connected block of DOM with its bindings.  The
- *   root component has one instance; conditionals and repeat items each get
- *   their own nested instance.
- *
- * - **ScopeFrame** — a linked-list frame for repeat variable scoping.
- *   `@for(item of items)` creates a frame `{ name: 'item', value, parent }`.
- *   Nested repeats chain frames so inner bindings can resolve outer variables.
- */
-import type { CompiledAttrMeta, CompiledAttrPart, CompiledCondition } from '../template.js';
-/** Direct reference to a text node bound to a property path. */
+import type { CompiledAttrPart, CompiledCondition } from '../template.js';
 export interface TextBinding {
     node: Text;
     path?: string;
     parts?: CompiledAttrPart[];
     scope?: ScopeFrame;
-    /** When true, the binding renders unescaped HTML via innerHTML on the
-     *  parent element instead of setting Text.data. Corresponds to the
-     *  triple-brace `{{{expr}}}` template syntax. */
     raw?: boolean;
-    /** The parent element for raw bindings — innerHTML is set here. */
     rawParent?: Element;
 }
-/** Attribute binding kind constants (matches compiled metadata). */
 export declare const ATTR_KIND_ATTRIBUTE = 0;
 export declare const ATTR_KIND_COMPLEX = 1;
 export declare const ATTR_KIND_BOOLEAN = 2;
 export declare const ATTR_KIND_TEMPLATE = 3;
-/** Direct reference to an attribute binding. */
+export declare function hasNativeLiveProperty(element: Element, name: string): boolean;
 export interface AttrBinding {
     element: Element;
     name: string;
@@ -49,24 +25,35 @@ export interface ScopeFrame {
     name: string;
     value: unknown;
     parent?: ScopeFrame;
+    known?: boolean;
 }
 export interface TemplateInstance {
     scope?: ScopeFrame;
+    parent?: TemplateInstance;
+    container: (ParentNode & Node) | null;
     nodes: Node[];
     texts: TextBinding[];
     attrs: AttrBinding[];
     conds: CondBinding[];
     repeats: RepeatBinding[];
+    cleanups?: Array<() => void>;
 }
-/** Direct reference to a conditional block with anchor + nested compiled block. */
 export interface CondBinding {
     condition: CompiledCondition;
     blockIndex: number;
     anchor: Comment;
     scope?: ScopeFrame;
+    owner: TemplateInstance;
     instance: TemplateInstance | null;
 }
-/** Repeat block tracking. */
+export type RepeatKey = string | number;
+export interface RepeatKeyState {
+    path: string;
+    warned: boolean;
+    keys: RepeatKey[];
+    nextKeys: RepeatKey[];
+    map: Map<RepeatKey, TemplateInstance | null>;
+}
 export interface RepeatBinding {
     markerId: number;
     collection: string;
@@ -77,30 +64,16 @@ export interface RepeatBinding {
     end: Comment | null;
     scope?: ScopeFrame;
     owner: TemplateInstance;
-    instances: RepeatItemInstance[];
-    rootTag: string | null;
-    attrMap: Record<string, string>;
-    rootBindings: CompiledAttrMeta[];
-    /** Set to true once the collection has been explicitly set by client code. */
+    instances: TemplateInstance[];
+    keyState?: RepeatKeyState;
     synced?: boolean;
 }
-export interface RepeatItemInstance {
-    key: string | null;
-    value: unknown;
-    instance: TemplateInstance;
-}
-/**
- * Minimal host interface for repeat operations.
- *
- * Repeat functions need access to host capabilities (value resolution,
- * block lookup, instance management) without depending on the full
- * WebUIElement class.
- */
 export interface RepeatHost {
     $resolveValue(path: string, scope?: ScopeFrame): unknown;
-    /** Create, wire, and perform the first binding pass while detached. */
-    $createBlockInstance(blockIndex: number, scope?: ScopeFrame): TemplateInstance | null;
+    $hasStateRoot(path: string, scope?: ScopeFrame): boolean;
+    $createBlockInstance(blockIndex: number, scope?: ScopeFrame, parent?: TemplateInstance, container?: ParentNode & Node): TemplateInstance | null;
     $updateInstance(instance: TemplateInstance): void;
     $removeInstance(instance: TemplateInstance): void;
+    $changeStructure(removedFrom?: TemplateInstance): void;
     $insertInstanceAfter(cursor: Node | null, container: ParentNode & Node, instance: TemplateInstance): Node | null;
 }

package/dist/element/types.js

@@ -1,7 +1,7 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-/** Attribute binding kind constants (matches compiled metadata). */
 export const ATTR_KIND_ATTRIBUTE = 0;
 export const ATTR_KIND_COMPLEX = 1;
 export const ATTR_KIND_BOOLEAN = 2;
 export const ATTR_KIND_TEMPLATE = 3;
+export function hasNativeLiveProperty(element, name) {
+    return element.localName.indexOf('-') === -1 && name in element;
+}

package/dist/element.d.ts

@@ -1,140 +1,22 @@
-import type { TemplateBlockMeta } from './template.js';
+import { TemplateElement } from './template-element.js';
+import type { TemplateBlockMeta, TemplateNodePath } from './template.js';
 import type { ScopeFrame, TemplateInstance } from './element/types.js';
-export declare class WebUIElement extends HTMLElement {
-    private $root;
-    private $meta?;
-    private $ready;
-    private $hydrated;
-    private $dirtyPaths;
-    private $pendingFlush;
-    /** Cached condition resolver — avoids allocating a closure per evaluation. */
-    private $resolver;
-    private $pathIndex?;
-    /** Bindings that reference non-observable paths — updated on every flush. */
-    private $wildcardBindings?;
-    static define(tagName: string): void;
-    connectedCallback(): void;
-    /** Mount the component after children are available. */
-    private $mount;
-    disconnectedCallback(): void;
-    /**
-     * Permanently destroy this component's own bindings and DOM references.
-     * Each component is responsible for its own cleanup — child WebUI
-     * elements handle theirs via their own `disconnectedCallback`.
-     */
-    $destroy(): void;
-    /** Break all DOM references held by a binding instance and its nested blocks. */
-    private $teardown;
-    /** Dispatch a bubbling custom event. Uses composed:true when in shadow DOM. */
+export declare class WebUIElement extends TemplateElement {
+    protected $observableNames(): Set<string>;
+    protected $shouldApplySSRState(key: string): boolean;
+    protected $syncAuthoredAttributes(): void;
     $emit(name: string, detail?: unknown): boolean;
-    /** Populate @observable properties from server or router state.
-     *
-     * Each property is set through its reactive setter, which coalesces
-     * updates into a single pending microtask. We then synchronously
-     * flush those pending path updates so the DOM is current before any
-     * view-transition snapshot captures it.
-     */
-    setState(state: Record<string, unknown>): void;
-    /**
-     * Apply SSR state from `window.__webui.state`.
-     *
-     * The handler emits all SSR metadata in a single consolidated
-     * `window.__webui` script block. State lives at `.state` — the same
-     * props passed to the server render so observables match the DOM.
-     * Only observable properties are set — unknown keys are ignored.
-     *
-     * Writes directly to the backing field (`_prop`) to avoid triggering
-     * reactive updates before bindings are wired.
-     */
-    private $applySSRState;
-    /** Reactive update — called by @observable/@attr setters. */
-    $update(path?: string): void;
-    /** Synchronously flush all queued path updates. Call this when you need
-     *  the DOM to reflect pending property changes immediately. */
-    $flushUpdates(): void;
-    /** Flush all queued path updates. Handles re-entrant setter calls. */
-    private $flush;
-    private $resolve;
-    private $resolveSSR;
-    private $parseTemplate;
-    private $createStagingRoot;
-    private $appendStagedChildren;
-    private $releaseStagingRepeatContainers;
-    private $wire;
-    /**
-     * Hydrate SSR-rendered DOM against compiled template metadata.
-     *
-     * When pathStart=0 (default): ssrRoot is a container with children
-     * (top-level component hydration).
-     *
-     * When pathStart=1: ssrRoot is a block element itself (repeat item
-     * in-place hydration). The leading [0] wrapper segment is skipped
-     * so compiled paths resolve directly against the element.
-     */
-    private $hydrate;
-    /** Collect sibling nodes between a start marker and an end marker comment. */
-    private $collectBetween;
-    /**
-     * Hydrate a conditional block's content — shared by top-level and
-     * repeat-item conditional hydration paths.
-     */
-    private $hydrateCondContent;
-    /**
-     * Find the next marker comment with the given data among a parent's children.
-     * Starts searching from `after` (exclusive) if provided, or from firstChild.
-     */
-    private $findMarker;
-    /**
-     * Check whether there is non-marker content between a conditional
-     * start anchor and its closing marker.  Used during SSR hydration to
-     * detect server-rendered conditional content even when the runtime
-     * condition value has not been set yet (e.g. complex property from a
-     * parent repeat binding that hydrates after its children).
-     */
-    private $hasContentAfterMarker;
-    /**
-     * Find existing SSR text node by mapping template text-node ordinal.
-     *
-     * Similar to `$resolveSSR`, the SSR DOM may contain extra text nodes
-     * inside structural blocks (`<if>`/`<for>`) that are not in the
-     * compiled template.  We skip `<!--wc-->...<!--/wc-->` and
-     * `<!--wr-->...<!--/wr-->` ranges to keep text ordinals aligned.
-     */
-    private $findSSRText;
-    /** Find the SSR insertion reference for an empty text slot. */
-    private $findSSRSlotRef;
-    /** Extract root tag name from block metadata. */
-    private $rootTag;
-    /** Wire attribute bindings using a resolver (shared by $wire and $hydrate). */
-    private $wireAttrs;
-    /** Wire events + root events + refs (shared by $wire and $hydrate). */
-    private $finalize;
-    /** Wire events using a resolver function (works for both client and SSR). */
+    protected $finalize(instance: TemplateInstance, root: Node, meta: TemplateBlockMeta, resolver: (root: Node, path: TemplateNodePath) => Node | null, scope?: ScopeFrame): void;
     private $wireEvents;
-    /** Wire root-level events on the host element (or shadow root when present). */
+    private $resolveDelegatedEvents;
     private $wireRoot;
-    /** Attach a single event listener. */
+    private $addDelegatedEvent;
+    private $dispatchDelegatedEvent;
     private $addEvent;
+    private $addCleanup;
+    private $callEventHandler;
+    private $callEventHandlerWithCurrentTarget;
     private $resolveEventArgs;
     private $resolveEventArg;
-    /** Find w-ref attributes and assign to component properties. */
     private $wireRefs;
-    /** Create an AttrBinding from compiled metadata. */
-    private $makeAttr;
-    /** Build attrMap and rootBindings for a repeat block. */
-    private $repeatMaps;
-    private $buildPathIndex;
-    private $updateBindings;
-    $updateInstance(instance: TemplateInstance): void;
-    private $patchText;
-    private $patchAttr;
-    private $toggleCond;
-    $resolveValue(path: string, scope?: ScopeFrame): unknown;
-    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;
-    /** Extract the single dynamic path from a compiled attr parts array. */
-    private $singleDynamic;
 }