@microsoft/webui-framework 0.0.17 → 0.0.18

package/dist/element/markers.js

@@ -1,38 +1,14 @@
-// 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 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;
@@ -45,16 +21,12 @@ export function collectItemMarkers(repeatStart) {
     }
     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)
                 return null;
@@ -63,38 +35,18 @@ export function nextElement(marker) {
     }
     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 +56,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);
         }, () => { });
     }
 }

package/dist/element/types.d.ts

@@ -1,41 +1,16 @@
-/**
- * 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 interface AttrBinding {
     element: Element;
     name: string;
@@ -57,8 +32,8 @@ export interface TemplateInstance {
     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;
@@ -66,7 +41,6 @@ export interface CondBinding {
     scope?: ScopeFrame;
     instance: TemplateInstance | null;
 }
-/** Repeat block tracking. */
 export interface RepeatBinding {
     markerId: number;
     collection: string;
@@ -79,9 +53,8 @@ export interface RepeatBinding {
     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. */
+    keyAttribute?: string;
+    keyPath?: string;
     synced?: boolean;
 }
 export interface RepeatItemInstance {
@@ -89,16 +62,8 @@ export interface RepeatItemInstance {
     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;
     $updateInstance(instance: TemplateInstance): void;
     $removeInstance(instance: TemplateInstance): void;

package/dist/element/types.js

@@ -1,6 +1,3 @@
-// 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;

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;
 }