@microsoft/webui-framework 0.0.4 → 0.0.5

package/dist/decorators.d.ts

@@ -0,0 +1,30 @@
+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;
+/**
+ * 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 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 attr(target: object, name: string): void;
+export declare function attr(options: AttrOptions): (target: object, name: string) => void;

package/dist/decorators.js

@@ -0,0 +1,95 @@
+function toKebabCase(str) {
+  return str.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+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 observableRegistry = /* @__PURE__ */ new WeakMap();
+const EMPTY_SET = Object.freeze(/* @__PURE__ */ new Set());
+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);
+}
+const attrMap = /* @__PURE__ */ new WeakMap();
+const boolAttrs = /* @__PURE__ */ 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());
+    }
+    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);
+}
+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.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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. */
+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 syncRepeat(host: RepeatHost, rep: RepeatBinding): void;

package/dist/element/diff.js

@@ -0,0 +1,117 @@
+function asParent(node) {
+  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;
+    }
+  }
+  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);
+}
+function itemKey(item, keyPath) {
+  if (keyPath === void 0 || keyPath === "") return null;
+  const v = dotWalk(item, keyPath, 0);
+  return v != null ? String(v) : "";
+}
+function itemScope(rep, item) {
+  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);
+    }
+    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);
+    }
+    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 });
+      }
+    }
+    for (let i = reuseCount; i < oldInstances.length; i += 1) {
+      host.$removeInstance(oldInstances[i].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);
+    }
+    for (let i = 0; i < next2.length; i += 1) {
+      host.$updateInstance(next2[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 });
+      }
+    }
+  }
+  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

@@ -0,0 +1,34 @@
+/**
+ * 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
+ */
+export declare const MARKER_REPEAT_START = "wr";
+export declare const MARKER_REPEAT_END = "/wr";
+export declare const MARKER_COND_START = "wc";
+export declare const MARKER_COND_END = "/wc";
+/**
+ * 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 declare function collectItemMarkers(repeatStart: Comment): {
+    items: Comment[];
+    end: Comment | null;
+};
+/**
+ * Get the next element sibling after a marker comment, skipping
+ * whitespace text nodes and other comments.
+ */
+export declare function nextElement(marker: Comment): Element | null;

package/dist/element/markers.js

@@ -0,0 +1,42 @@
+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);
+    }
+    node = node.nextSibling;
+  }
+  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;
+    }
+    node = node.nextSibling;
+  }
+  return null;
+}
+export {
+  MARKER_COND_END,
+  MARKER_COND_START,
+  MARKER_REPEAT_END,
+  MARKER_REPEAT_START,
+  collectItemMarkers,
+  nextElement
+};

package/dist/element/styles.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function injectModuleStyle(specifier: string, shadowRoot: ShadowRoot | null): void;

package/dist/element/styles.js

@@ -0,0 +1,29 @@
+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;
+    }
+  }
+  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.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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. */
+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;
+    kind: number;
+    path?: string;
+    condition?: CompiledCondition;
+    parts?: CompiledAttrPart[];
+    scope?: ScopeFrame;
+}
+export interface ScopeFrame {
+    name: string;
+    value: unknown;
+    parent?: ScopeFrame;
+}
+export interface TemplateInstance {
+    scope?: ScopeFrame;
+    nodes: Node[];
+    texts: TextBinding[];
+    attrs: AttrBinding[];
+    conds: CondBinding[];
+    repeats: RepeatBinding[];
+}
+/** Direct reference to a conditional block with anchor + nested compiled block. */
+export interface CondBinding {
+    condition: CompiledCondition;
+    blockIndex: number;
+    anchor: Comment;
+    scope?: ScopeFrame;
+    instance: TemplateInstance | null;
+}
+/** Repeat block tracking. */
+export interface RepeatBinding {
+    markerId: number;
+    collection: string;
+    itemVar: string;
+    blockIndex: number;
+    container: (ParentNode & Node) | null;
+    start: Comment | null;
+    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. */
+    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;
+    $createBlockInstance(blockIndex: number, scope?: ScopeFrame): TemplateInstance | null;
+    $updateInstance(instance: TemplateInstance): void;
+    $removeInstance(instance: TemplateInstance): void;
+    $insertInstanceAfter(cursor: Node | null, container: ParentNode & Node, instance: TemplateInstance): Node | null;
+}

package/dist/element/types.js

@@ -0,0 +1,10 @@
+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
+};

package/dist/element.d.ts

@@ -0,0 +1,104 @@
+import type { TemplateBlockMeta } 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;
+    /** Dispatch a bubbling custom event. Uses composed:true when in shadow DOM. */
+    $emit(name: string, detail?: unknown): boolean;
+    /** Populate @observable properties from router state. */
+    setInitialState(state: Record<string, unknown>): void;
+    /**
+     * Apply SSR state from the global `window.__webui_state` object.
+     *
+     * Passing the same props to both server render and client
+     * hydrate, this ensures component observables match the server-rendered
+     * DOM. The handler emits the state as a `<script>` tag at the end of
+     * the page. 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 $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;
+    /** Find existing SSR text node by mapping template text-node ordinal. */
+    private $findSSRText;
+    /** 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). */
+    private $wireEvents;
+    /** Wire root-level events on the host element (or shadow root when present). */
+    private $wireRoot;
+    /** Attach a single event listener. */
+    private $addEvent;
+    /** 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;
+}