diff --git a/DESIGN.md b/DESIGN.md index 6c616db6..7e124afd 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1341,7 +1341,12 @@ WebUI Framework hydration assumes the SSR DOM, hydration markers, and compiled m `@microsoft/webui-framework` consumes the metadata object above plus the SSR markers emitted by `WebUIHydrationPlugin`. This follows an Islands Architecture approach: the server delivers fully-rendered HTML, and only interactive Web Components hydrate on the client — leaving static content untouched. - SSR hydration uses one DOM walk to discover ``, ``, and `` comment markers, wire the relevant bindings using compiled metadata path indices, then remove SSR-only markers. -- Client-created DOM never reparses template syntax; it clones marker-free `h` and resolves `tx`, `ag`, `cl`, `rl`, and event target paths directly. +- Client-created DOM never reparses template syntax; it clones marker-free `h`, + upgrades the detached custom-element subtree, resolves `tx`, `ag`, `cl`, `rl`, + and event target paths directly, then applies the first binding pass before + appending nodes to the connected DOM. Child components therefore observe + initial parent `:` property bindings in `connectedCallback`, while later parent + updates remain live. - Events are resolved from compiled `e[]` metadata entries using path indices. The runtime installs listeners on target elements and resolves handler arguments against the scope captured when that block was rendered. Root events from `re[]` attach directly to the host element. - The full package entrypoint supports repeat metadata (`r[]` / `rl[]`). The additive `@microsoft/webui-framework/element-no-repeat` entrypoint preserves the same public `WebUIElement` API but must reject compiled templates that contain repeat metadata. diff --git a/docs/ai.md b/docs/ai.md index eb345717..18f3bb7f 100644 --- a/docs/ai.md +++ b/docs/ai.md @@ -182,6 +182,12 @@ Supported operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `&&`, `||`, `!` ``` +Property bindings use `:` to write directly to DOM properties. For +client-created component trees, initial property bindings are applied before a +child component's `connectedCallback` runs. Children can read parent-provided +values during setup, initialize their own fallback when a value is missing, and +still receive later parent updates through the live binding. + ### Events (client-side only) ```html diff --git a/docs/guide/concepts/interactivity.md b/docs/guide/concepts/interactivity.md index 6ff084e5..f4263292 100644 --- a/docs/guide/concepts/interactivity.md +++ b/docs/guide/concepts/interactivity.md @@ -230,6 +230,16 @@ Toggle HTML attributes with the `?` prefix:
...
``` +### Property Bindings + +Use the `:` prefix to pass rich values directly to child DOM properties: + +```html + +``` + +For client-created component trees, WebUI applies initial property bindings before child `connectedCallback` methods run. This lets a child read a parent-provided property during setup. If the parent has not provided a value, the child can initialize a fallback in `connectedCallback`; later parent updates still flow through the live binding. + ### List Rendering Iterate over arrays with ``: diff --git a/packages/webui-framework/README.md b/packages/webui-framework/README.md index 2cb17175..c9bc4d42 100644 --- a/packages/webui-framework/README.md +++ b/packages/webui-framework/README.md @@ -95,6 +95,16 @@ cargo run -p microsoft-webui-cli -- build ./src --out ./dist --plugin=webui The compiler/plugin generates the template metadata consumed by the runtime. In normal app code, you should not need to hand-author `window.__webui.templates`. +### Property binding lifecycle + +Property bindings use the `:` prefix to pass values directly to child DOM properties: + +```html + +``` + +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. + ### DOM strategy (`--dom`) The `--dom` flag controls how the server renders component content: diff --git a/packages/webui-framework/RENDERING.md b/packages/webui-framework/RENDERING.md index 49ee700f..5dbdb9d2 100644 --- a/packages/webui-framework/RENDERING.md +++ b/packages/webui-framework/RENDERING.md @@ -39,7 +39,7 @@ Compile metadata Inject SSR markers existing DOM, 1. **Server renders HTML.** The handler walks compiled template metadata and application state and emits Declarative Shadow DOM (or light DOM) with five comment markers around structural blocks, plus a `