@microsoft/webui-framework 0.0.6 → 0.0.7

package/dist/element/markers.js

@@ -1,42 +1,121 @@
-const MARKER_REPEAT_START = "wr";
-const MARKER_REPEAT_END = "/wr";
-const MARKER_COND_START = "wc";
-const MARKER_COND_END = "/wc";
-const MARKER_REPEAT_ITEM = "wi";
-function collectItemMarkers(repeatStart) {
-  const items = [];
-  let end = null;
-  let node = repeatStart.nextSibling;
-  while (node) {
-    if (node.nodeType === 8) {
-      const data = node.data;
-      if (data === MARKER_REPEAT_END) {
-        end = node;
-        break;
-      }
-      if (data === MARKER_REPEAT_ITEM) items.push(node);
+// 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 */) {
+            const data = node.data;
+            if (data === MARKER_REPEAT_END) {
+                end = node;
+                break;
+            }
+            if (data === MARKER_REPEAT_ITEM)
+                items.push(node);
+        }
+        node = node.nextSibling;
     }
-    node = node.nextSibling;
-  }
-  return { items, end };
+    return { items, end };
 }
-function nextElement(marker) {
-  let node = marker.nextSibling;
-  while (node) {
-    if (node.nodeType === 1) return node;
-    if (node.nodeType === 8) {
-      const data = node.data;
-      if (data === MARKER_REPEAT_END || data === MARKER_REPEAT_ITEM) return null;
+/**
+ * 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 */)
+            return node;
+        if (node.nodeType === 8 /* COMMENT_NODE */) {
+            const data = node.data;
+            if (data === MARKER_REPEAT_END || data === MARKER_REPEAT_ITEM)
+                return null;
+        }
+        node = node.nextSibling;
     }
-    node = node.nextSibling;
-  }
-  return null;
+    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 */) {
+            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 */) {
+                        const d = child.data;
+                        if (d === data)
+                            depth++;
+                        else if (d === endTag)
+                            depth--;
+                    }
+                    if (depth > 0)
+                        child = child.nextSibling;
+                }
+                // Advance past the closing marker itself
+                if (child)
+                    child = child.nextSibling;
+                continue;
+            }
+        }
+        if (child.nodeType === nodeType) {
+            if (count === ordinal)
+                return child;
+            count++;
+        }
+        child = child.nextSibling;
+    }
+    return null;
 }
-export {
-  MARKER_COND_END,
-  MARKER_COND_START,
-  MARKER_REPEAT_END,
-  MARKER_REPEAT_START,
-  collectItemMarkers,
-  nextElement
-};

package/dist/element/styles.d.ts

@@ -1,7 +1,11 @@
 /**
- * Inject a CSS module stylesheet. Shadow DOM components get a
- * constructable stylesheet on their shadow root; light DOM components
- * get a `<style>` in the document head. Each specifier is processed
- * once per page.
+ * 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,29 +1,77 @@
-const injectedStyles = /* @__PURE__ */ new Set();
-function injectModuleStyle(specifier, shadowRoot) {
-  if (injectedStyles.has(specifier)) return;
-  injectedStyles.add(specifier);
-  const defs = document.querySelectorAll('style[type="module"][specifier]');
-  let cssText = null;
-  for (let i = 0; i < defs.length; i++) {
-    if (defs[i].getAttribute("specifier") === specifier) {
-      cssText = defs[i].textContent;
-      break;
+// 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 the Declarative CSS Module Scripts proposal. During SSR,
+ *   `<style type="module" specifier="...">` definitions are emitted inline in
+ *   each rendered component's light DOM. The browser registers these globally
+ *   and automatically adopts them via `shadowrootadoptedstylesheets` on
+ *   declarative shadow roots.
+ *
+ *   During SPA navigation, the router appends new `<style type="module">`
+ *   definitions 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 <style type="module" specifier="X"> definition was either
+        // emitted inline during SSR or appended to <head> by the router.
+        // The import resolves to the same CSSStyleSheet the browser registered.
+        import(specifier, { with: { type: 'css' } }).then((mod) => {
+            shadowRoot.adoptedStyleSheets = [
+                ...shadowRoot.adoptedStyleSheets,
+                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);
+        }, () => { });
     }
-  }
-  if (!cssText) return;
-  if (shadowRoot) {
-    const sheet = new CSSStyleSheet();
-    sheet.replaceSync(cssText);
-    shadowRoot.adoptedStyleSheets = [
-      ...shadowRoot.adoptedStyleSheets,
-      sheet
-    ];
-  } else {
-    const style = document.createElement("style");
-    style.textContent = cssText;
-    document.head.appendChild(style);
-  }
 }
-export {
-  injectModuleStyle
-};

package/dist/element/types.js

@@ -1,10 +1,7 @@
-const ATTR_KIND_ATTRIBUTE = 0;
-const ATTR_KIND_COMPLEX = 1;
-const ATTR_KIND_BOOLEAN = 2;
-const ATTR_KIND_TEMPLATE = 3;
-export {
-  ATTR_KIND_ATTRIBUTE,
-  ATTR_KIND_BOOLEAN,
-  ATTR_KIND_COMPLEX,
-  ATTR_KIND_TEMPLATE
-};
+// 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;

package/dist/element.d.ts

@@ -67,7 +67,14 @@ export declare class WebUIElement extends HTMLElement {
      * Starts searching from `after` (exclusive) if provided, or from firstChild.
      */
     private $findMarker;
-    /** Find existing SSR text node by mapping template text-node ordinal. */
+    /**
+     * 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;
     /** Extract root tag name from block metadata. */
     private $rootTag;