@microsoft/webui-framework 0.0.17 → 0.0.18

package/README.md

@@ -6,9 +6,9 @@ This package is the browser-side runtime used by `webui build --plugin=webui`. I
 
 - `WebUIElement` for SSR hydration and client-created elements
 - `@observable`, `@attr`, and `@volatile` decorators
-- compiled template path mapping for direct DOM binding resolution
+- direct DOM binding updates
 - light DOM or shadow DOM rendering (`--dom=light|shadow` flag)
-- SSR state seeding from `window.__webui.state` (like Preact's props)
+- SSR state seeding
 
 If you are building WebUI apps in this repo, this is the component model used by examples like `examples/app/todo-webui`, `examples/app/commerce`, and `examples/app/contact-book-manager`.
 
@@ -87,13 +87,33 @@ Build with `--dom=shadow` (default) to wrap in a declarative shadow root, or `--
 <counter-card label="Taps"></counter-card>
 ```
 
+### HTML-only components
+
+If a component has no event handlers, custom lifecycle code, or client-only
+methods, it can ship only `component.html` and optional `component.css`.
+
+When HTML-only components receive server or route state, import
+`@microsoft/webui-framework` somewhere in the browser entry. The framework root
+installs the static host runtime, which only claims compiler-owned HTML-only
+components whose templates need hidden state or observed host attributes. Fully
+static HTML-only components stay as plain SSR DOM.
+
+Create a custom element only for an Interactive Island: event handlers, custom
+lifecycle code, imperative methods, or state that TypeScript code reads or
+mutates. `@observable` and `@attr` are optional; add them when JavaScript needs
+to access the value or when the value is part of the component's public API.
+
 ### Build with the WebUI plugin
 
 ```bash
 cargo run -p microsoft-webui-cli -- build ./src --out ./dist --plugin=webui
 ```
 
-The compiler/plugin generates the template metadata and condition closure arrays consumed by the runtime. In normal app code, you should not need to hand-author `window.__webui.templates` or `window.__webui.templateFns`.
+The WebUI plugin prepares component templates for the browser. Bundle your
+source browser entry directly. Import `@microsoft/webui-framework` from authored
+component modules, or once from the browser entry when the app has no authored
+components but still uses HTML-only components that receive server or route
+state.
 
 ### Property binding lifecycle
 
@@ -103,7 +123,22 @@ Property bindings use the `:` prefix to pass values directly to child DOM proper
 <profile-card :config="{{settings}}"></profile-card>
 ```
 
-For client-created component trees, the runtime upgrades the cloned child elements while they are still detached, wires bindings, and applies the first binding pass before appending them to the connected DOM. A child can read an initial parent-provided property in `connectedCallback`. If the parent value is not set, the child may initialize its own fallback there, and later parent updates still flow through the live binding.
+For client-created component trees, WebUI applies initial property bindings
+before child `connectedCallback` methods run. A child can read an initial
+parent-provided property in `connectedCallback`. If the parent value is not set,
+the child may initialize its own fallback there, and later parent updates still
+flow through the live binding.
+
+During SSR hydration the framework trusts the server-rendered DOM and does not
+re-render it. An `@observable` written before hydration finishes — in a field
+initializer, the `constructor`, or before `super.connectedCallback()` — cannot
+update that DOM, so the write is dropped and the runtime logs a
+`[WebUI] Hydration mismatch` warning naming the properties. Seed such values in
+the SSR state, or assign them after `super.connectedCallback()`. The warning is
+development-only and is dead-code-eliminated from production bundles via the
+`__WEBUI_DEV__` compile-time flag (on by default; `webui-press build` sets it to
+`false`). See the
+[Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity#setting-observable-state-during-setup).
 
 ### DOM strategy (`--dom`)
 
@@ -135,15 +170,50 @@ Base class for framework components.
 | `static define(tagName)` | Register the class as a custom element |
 | `$emit(name, detail?)` | Dispatch a bubbling, composed `CustomEvent` |
 | `$update()` | Force a reactive update (normally called automatically) |
-| `setState(state)` | Populate `@observable` properties from router/server state |
 | `disconnectedCallback()` | Override for cleanup (global listeners, etc.) |
 
 In most components you do not call `$update()` directly. Property changes through `@observable` and `@attr` trigger updates for you.
 
+### Static component assets
+
+`webui build --plugin=webui --emit-component-assets settings-dialog` emits
+`settings-dialog.webui.js` next to `protocol.bin`. Load the ESM asset before
+creating the component when you are not using `@microsoft/webui-router`:
+
+```ts
+import { settingsAssets } from './lazy-assets.js';
+
+settingsAssets.preload('settings-dialog');
+panelSlot.replaceChildren(await settingsAssets.create('settings-dialog'));
+```
+
+```ts
+// lazy-assets.ts
+import { defineComponentAssets } from '@microsoft/webui-framework/component-asset.js';
+
+export const settingsAssets = defineComponentAssets({
+  'settings-dialog': {
+    asset: '/settings-dialog.webui.js',
+    module: () => import('./settings-dialog/settings-dialog.js'),
+    data: async () => await (await fetch('/settings-dialog-data.json')).json(),
+  },
+});
+```
+
+The asset module carries the component's template and style payload. Use
+`preload(tag)` to start template, module, and optional data work early, then
+`create(tag)` to create the element after template/module work is ready.
+Concurrent asset requests share one in-flight load and CSS module styles are
+deduped. `create(tag)` does not block on optional data by default. Use
+`create(tag, { awaitData: true, dataTimeoutMs: 150 })` only when a component must
+wait briefly for state before mounting.
+
 ### `@observable`
 
-Marks a property as reactive.  When the value changes, the framework
-re-evaluates the compiled bindings that reference it.
+Marks a property as reactive. When the value changes, the framework
+updates template bindings that reference it. Use it for state that TypeScript
+code reads or mutates. Values used only by the template do not need an
+`@observable` class field.
 
 ```ts
 class SearchPanel extends WebUIElement {
@@ -170,7 +240,7 @@ Notes:
 
 - default attribute names use kebab-case
 - attribute values arrive as strings
-- use `@observable` for richer client-only state
+- use `@observable` for state that client code reads or mutates
 
 ### `@volatile`
 
@@ -189,7 +259,7 @@ class CartSummary extends WebUIElement {
 
 ## Template Features
 
-The WebUI plugin compiles these template features into runtime metadata:
+The WebUI plugin supports these template features:
 
 - text bindings: `{{title}}`
 - attribute bindings: `href="{{item.href}}"`
@@ -198,6 +268,9 @@ The WebUI plugin compiles these template features into runtime metadata:
 - conditionals: `<if condition="...">`
 - repeats: `<for each="item in items">`
 
+Components that use `@event` must have authored `.ts` or `.js` code that
+defines a `WebUIElement` for the tag; HTML-only components are declarative only.
+
 Example from `examples/app/todo-webui`:
 
 ```html
@@ -222,11 +295,15 @@ Root-level events (e.g. `@toggle-item="{onToggleItem(e)}"`) can be declared on t
 
 ## Recommended Patterns
 
-- Treat decorated properties as the source of truth.
+- Treat decorated properties as the source of truth for state used by
+  TypeScript code.
 - Update state with property assignments such as `this.open = !this.open`.
 - Use `$emit()` for child-to-parent communication.
 - Use `w-ref` for true DOM-only concerns like focus or reading input values.
-- Prefer `@observable someValue!: T;` when a value is expected to be seeded externally after construction.
+- Omit `@observable` for values that are only read by the template and seeded
+  externally after construction.
+- Omit the TypeScript class for HTML-only components that only need template
+  bindings and router/server state.
 
 Avoid imperative DOM mutation for application state that can be represented by reactive properties.
 
@@ -407,7 +484,7 @@ sequenceDiagram
     CE->>CE: attributeChangedCallback (pre-existing attrs)
     CE->>FW: connectedCallback() → $mount()
     FW->>FW: SSR DOM detected (shadow root or children exist)
-    FW->>FW: $applySSRState() — seed observables from __webui.state
+    FW->>FW: $applySSRState() — seed decorated + template state
     FW->>FW: $hydrate() — template-parallel path resolution
     FW->>FW: $resolveSSR() — match SSR nodes via ordinal traversal
     FW->>FW: $wireEvents() + $wireRefs()
@@ -454,15 +531,14 @@ interface TemplateMeta {
   tx?: [slot, parts][];                // Text run locators
   a?: CompiledAttrMeta[];              // Attribute bindings
   ag?: [path, start, count][];         // Attribute target groups
-  c?: [conditionAST, blockIndex][];    // Conditional blocks
-  cl?: SlotPath[];                     // Conditional anchor slots
-  r?: [collection, itemVar, blockIdx][];// Repeat blocks
-  rl?: SlotPath[];                     // Repeat anchor slots
-  e?: [event, handler, argSpecs, targetPath][]; // Events
+  c?: [conditionAST, blockIndex, slot][]; // Conditional blocks
+  r?: [collection, itemVar, blockIdx, slot][]; // Repeat blocks
+  eg?: [event, [[handler, argSpecs, targetPath, usesEvent?]]][]; // Events
   b?: TemplateBlockMeta[];             // Nested block metadata
   sa?: string;                         // Adopted stylesheet specifier
   sd?: boolean;                        // Shadow DOM flag for client-created
   re?: [event, handler, argSpecs][];    // Root-level events
+  th?: 1;                               // Compiler-owned static host
 }
 ```
 
@@ -482,7 +558,7 @@ Compiled metadata:
     [[[0], 0], [["title"]]],           // slot in <h1>, dynamic "title"
     [[[1], 1], ["Count: ", ["count"]]]  // slot in <button>, static + dynamic
   ],
-  e: [["click", "increment", [], [1]]] // click -> increment, no event args
+  eg: [["click", [["increment", [], [1]]]]] // click -> increment, no event args
 }
 ```
 
@@ -523,15 +599,16 @@ sequenceDiagram
 ### Why Updates Are O(affected)
 
 After hydration, every dynamic value in the template is connected to a direct
-DOM node reference stored in a binding array.  A per-path index maps each
-`@observable` property name to the subset of bindings that reference it.
+DOM node reference stored in a binding array. A per-path index maps each
+decorated property or compiled template root to the subset of bindings that
+reference it.
 
 When `this.count = 5` fires, the `@observable` setter calls `$update('count')`,
 which looks up `'count'` in the index and only patches the bindings that
 actually depend on `count` — not every binding in the component.
 
-Computed/volatile getters (paths not in the `@observable` set) are stored
-under a wildcard key and always included in targeted updates.
+Computed/volatile getters and other paths that are not known state roots are
+stored under a wildcard key and always included in targeted updates.
 
 ```typescript
 // Targeted update (simplified):
@@ -553,27 +630,29 @@ path index ensures only affected pointers are visited.
 
 ## SSR State Seeding
 
-When the server renders `<span>42</span>` for `@observable count = 0`, the
-browser sees `42` in the DOM but the JavaScript property `this.count` is still
-`0` (the class default).  Without seeding, the first `$update()` would
-overwrite the SSR content with the wrong value.
+When the server renders `<span>42</span>` for a template binding, the browser
+sees `42` in the DOM before the component's JavaScript state exists. Without
+seeding, the first `$update()` would overwrite the SSR content with the wrong
+value.
 
 State seeding uses `window.__webui.state` — a JSON object loaded from the
 server-emitted `#webui-data` block.  Like Preact's props, this delivers the
-same data used for SSR rendering to the client.  During `$mount()`,
-`$applySSRState()` writes matching keys directly to observable backing fields
-before any bindings are wired:
+same data used for SSR rendering to the client. During `$mount()`,
+`$applySSRState()` writes matching decorated keys directly to observable backing
+fields and stores undecorated template roots in hidden framework state before
+any bindings are wired:
 
 ```mermaid
 flowchart LR
     SCRIPT["&lt;script type='application/json' id='webui-data'&gt;<br/>{ state: { count: 42, title: 'Hello' } }"] --> APPLY["$applySSRState()"]
-    APPLY --> SEED["Write to backing fields:<br/>this._count = 42<br/>this._title = 'Hello'"]
+    APPLY --> SEED["Write decorated fields + hidden template state"]
     SEED --> HYDRATE["$hydrate() — bindings match<br/>server-rendered DOM"]
 ```
 
-`$applySSRState()` only sets properties that exist in the component's
-`@observable` set — unknown keys are ignored.  Writes go to the backing
-field (`_prop`) directly, avoiding reactive updates before bindings are wired.
+`$applySSRState()` only accepts keys that are decorated properties or compiled
+template roots. Unknown keys are ignored. Decorated writes go to the backing
+field (`_prop`) directly, and undecorated template roots stay internal, avoiding
+reactive updates before bindings are wired.
 
 ---
 

package/dist/component-asset.d.ts

@@ -0,0 +1,30 @@
+import { type CompiledConditionFn, type TemplateMeta } from './template.js';
+export interface ComponentAsset {
+    type?: 'webui-component-asset';
+    version?: number;
+    components?: string[];
+    templateStyles?: string[];
+    templates?: Record<string, TemplateMeta>;
+    templateFunctions?: Record<string, CompiledConditionFn[]>;
+}
+export type ComponentAssetState = Record<string, unknown>;
+export interface ComponentAssetManifestEntry<Data extends ComponentAssetState = ComponentAssetState> {
+    asset: string | URL;
+    module?: () => Promise<unknown>;
+    data?: () => Promise<Data>;
+}
+export type ComponentAssetManifest = Record<string, ComponentAssetManifestEntry>;
+export interface ComponentAssetPreload<Data extends ComponentAssetState = ComponentAssetState> {
+    asset: Promise<void>;
+    module?: Promise<unknown>;
+    data?: Promise<Data>;
+}
+export interface ComponentAssetCreateOptions {
+    awaitData?: boolean;
+    dataTimeoutMs?: number;
+}
+export interface ComponentAssetRegistry {
+    preload<Data extends ComponentAssetState = ComponentAssetState>(tag: string): ComponentAssetPreload<Data>;
+    create(tag: string, options?: ComponentAssetCreateOptions): Promise<HTMLElement>;
+}
+export declare function defineComponentAssets(manifest: ComponentAssetManifest): ComponentAssetRegistry;

package/dist/component-asset.js

@@ -0,0 +1,213 @@
+import { getTemplate, registerTemplateData, } from './template.js';
+const ASSET_TYPE = 'webui-component-asset';
+const ASSET_VERSION = 1;
+const injectedAssetStyles = new Set();
+const assetLoadPromises = new Map();
+let assetStylesSeeded = false;
+function assetGlobal() {
+    return window.__webui;
+}
+export function defineComponentAssets(manifest) {
+    const preloads = new Map();
+    function preload(tag) {
+        const existing = preloads.get(tag);
+        if (existing)
+            return existing;
+        const entry = manifest[tag];
+        if (!entry) {
+            throw new Error(`[WebUI] No component asset manifest entry for <${tag}>.`);
+        }
+        const next = {
+            asset: loadComponentAsset(tag, entry.asset),
+        };
+        if (entry.module) {
+            next.module = entry.module();
+        }
+        if (entry.data) {
+            next.data = entry.data();
+        }
+        next.asset.catch(() => { });
+        next.module?.catch(() => { });
+        next.data?.catch(() => { });
+        preloads.set(tag, next);
+        return next;
+    }
+    async function create(tag, options = {}) {
+        const pending = preload(tag);
+        await waitForElementResources(pending);
+        const element = document.createElement(tag);
+        if (pending.data) {
+            if (options.awaitData) {
+                const state = options.dataTimeoutMs === undefined
+                    ? await pending.data
+                    : await dataWithTimeout(pending.data, options.dataTimeoutMs);
+                if (state) {
+                    applyState(element, state);
+                }
+                else {
+                    applyDataWhenReady(element, pending.data);
+                }
+            }
+            else {
+                applyDataWhenReady(element, pending.data);
+            }
+        }
+        return element;
+    }
+    return { preload, create };
+}
+async function waitForElementResources(pending) {
+    await pending.asset;
+    if (pending.module)
+        await pending.module;
+}
+function applyState(element, state) {
+    const setState = element.setState;
+    if (typeof setState === 'function') {
+        setState.call(element, state);
+    }
+}
+function applyDataWhenReady(element, data) {
+    const elementRef = new WeakRef(element);
+    void data.then(state => {
+        const liveElement = elementRef.deref();
+        if (liveElement)
+            applyState(liveElement, state);
+    }).catch(() => { });
+}
+function dataWithTimeout(data, timeoutMs) {
+    if (timeoutMs < 0)
+        return data;
+    return Promise.race([
+        data,
+        new Promise(resolve => {
+            setTimeout(() => resolve(undefined), timeoutMs);
+        }),
+    ]);
+}
+function loadComponentAsset(tag, url) {
+    if (getTemplate(tag))
+        return Promise.resolve();
+    const assetUrl = new URL(url, document.baseURI);
+    const href = assetUrl.href;
+    let promise = assetLoadPromises.get(href);
+    if (promise)
+        return promise;
+    promise = importAndRegisterComponentAsset(assetUrl)
+        .finally(() => {
+        assetLoadPromises.delete(href);
+    });
+    assetLoadPromises.set(href, promise);
+    return promise;
+}
+function registerComponentAsset(asset) {
+    validateAsset(asset);
+    if (asset.templates && templatesAlreadyRegistered(asset.templates))
+        return;
+    registerAssetStyles(asset.templateStyles, readNonce());
+    if (asset.templates) {
+        registerTemplateData(asset.templates, asset.templateFunctions);
+    }
+}
+async function importAndRegisterComponentAsset(assetUrl) {
+    const imported = await import(assetUrl.href);
+    registerComponentAsset(readComponentAssetModule(imported));
+}
+function readComponentAssetModule(module) {
+    if (!isObject(module) || !isObject(module.default)) {
+        throw new Error('[WebUI] Component asset module must default-export an asset object.');
+    }
+    return module.default;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function validateAsset(asset) {
+    if (asset.type !== ASSET_TYPE) {
+        throw new Error(`[WebUI] Invalid component asset type: ${String(asset.type)}`);
+    }
+    if (asset.version !== ASSET_VERSION) {
+        throw new Error(`[WebUI] Unsupported component asset version: ${String(asset.version)}`);
+    }
+}
+function templatesAlreadyRegistered(templates) {
+    const tags = Object.keys(templates);
+    if (tags.length === 0)
+        return false;
+    for (let i = 0; i < tags.length; i++) {
+        if (!getTemplate(tags[i]))
+            return false;
+    }
+    return true;
+}
+function readNonce() {
+    const nonce = assetGlobal()?.nonce;
+    if (nonce)
+        return nonce;
+    const meta = document.querySelector('meta[name="webui-nonce"]');
+    return meta?.content ?? '';
+}
+function seedAssetStyleSet() {
+    if (assetStylesSeeded)
+        return;
+    assetStylesSeeded = true;
+    const styles = assetGlobal()?.styles;
+    if (!styles)
+        return;
+    for (let i = 0; i < styles.length; i++) {
+        injectedAssetStyles.add(styles[i]);
+    }
+}
+function registerAssetStyles(templateStyles, nonce) {
+    if (!templateStyles || templateStyles.length === 0)
+        return;
+    seedAssetStyleSet();
+    for (let i = 0; i < templateStyles.length; i++) {
+        const imports = parseImportMap(templateStyles[i]);
+        const nextImports = {};
+        let hasNewImport = false;
+        const specifiers = Object.keys(imports);
+        for (let j = 0; j < specifiers.length; j++) {
+            const specifier = specifiers[j];
+            if (injectedAssetStyles.has(specifier))
+                continue;
+            injectedAssetStyles.add(specifier);
+            nextImports[specifier] = imports[specifier];
+            hasNewImport = true;
+        }
+        if (!hasNewImport)
+            continue;
+        const script = document.createElement('script');
+        script.type = 'importmap';
+        if (nonce)
+            script.nonce = nonce;
+        script.textContent = JSON.stringify({ imports: nextImports });
+        document.head.appendChild(script);
+    }
+}
+function parseImportMap(scriptMarkup) {
+    const trimmed = scriptMarkup.trim();
+    if (!trimmed.startsWith('<script')) {
+        throw new Error('[WebUI] Component asset templateStyles entry must be a <script type="importmap"> tag.');
+    }
+    const openTagEnd = trimmed.indexOf('>');
+    const closeTagStart = trimmed.lastIndexOf('</script>');
+    if (openTagEnd < 0 || closeTagStart <= openTagEnd) {
+        throw new Error('[WebUI] Component asset importmap tag is malformed.');
+    }
+    const parsed = JSON.parse(trimmed.substring(openTagEnd + 1, closeTagStart));
+    if (!parsed.imports || typeof parsed.imports !== 'object') {
+        throw new Error('[WebUI] Component asset importmap is missing an imports object.');
+    }
+    const imports = {};
+    const specifiers = Object.keys(parsed.imports);
+    for (let i = 0; i < specifiers.length; i++) {
+        const specifier = specifiers[i];
+        const uri = parsed.imports[specifier];
+        if (typeof uri !== 'string' || !uri.startsWith('data:text/css,')) {
+            throw new Error(`[WebUI] Component asset importmap entry "${specifier}" must be a data:text/css URI.`);
+        }
+        imports[specifier] = uri;
+    }
+    return imports;
+}

package/dist/decorators.d.ts

@@ -1,62 +1,11 @@
-/**
- * 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 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;