feat(parser): propagate template host attrs onto declarative shadow DOM host (FAST plugins)

[janechu]

Summary

Mirrors microsoft/fast#7521 in webui. When the FAST v2 or FAST v3 parser plugin is active and the Shadow DOM strategy is in use, static attributes declared on the inner root <template> of a component definition are now propagated onto every host custom-element opening tag during SSR.

Behavior

• Author wins on conflict. Attributes set at the usage site take precedence over template host attrs. Conflict detection strips leading : or ? from the author name so binding forms (:foo, ?disabled) suppress the static propagation. @ event prefixes do not suppress (they target a different namespace).
• Client-only directives are skipped: names starting with @, :, or ?, and the literal names f-ref, f-slotted, f-children.
• Template-internal attrs are skipped: shadowrootmode, shadowrootadoptedstylesheets.
• Dynamic {{ ... }} host attribute values are out of scope for this pass — only fully static template host attrs propagate.
• Only the root <template> wrapper of the component definition is consulted; nested templates are ignored.
• Light DOM rendering is unaffected (no declarative shadow root, so no propagation).
• WebUI parser plugin keeps the default of false — propagation is FAST-only by design.

Implementation

• New default-false hook on ParserPlugin:

  fn propagate_template_host_attrs(&self) -> bool { false }

  FAST v2 and FAST v3 plugins override to return true.
• HtmlParser::template_host_attrs_cache: HashMap<String, Vec<TemplateHostAttr>> parses each component's host attributes exactly once per unique tag name.
• New helpers (extract_template_host_attrs, propagate_template_host_attrs_to_host, etc.) use tree-sitter with iterative traversal — no recursion, no regex per the performance contract.
• Propagation is spliced after process_tag_attributes and before the plugin's finish_element hook so FAST binding markers remain after the real host attributes on the rendered opening tag.

Docs

• DESIGN.md — documented the new trait hook and the propagation contract under the Parser Plugin System section.
• docs/guide/concepts/plugins/index.md — added the hook to the public ParserPlugin trait reference with an opt-in description.

Tests

• Per-plugin overrides for FAST v2, FAST v3, WebUI verifying the opt-in value.
• Core unit tests for extract_template_host_attrs: no template wrapper, static attr extraction, skipping of @/:/?/f-*/shadowroot* names, skipping of dynamic {{…}} values, root-only behavior.
• End-to-end propagation tests: FAST v2/v3 propagation, WebUI no-propagation, author-wins conflict (incl. ? normalization), @click does not suppress an unrelated static attribute, Light DOM gating, and per-tag caching observed via the cache field.

Quality gate

cargo xtask check passes locally (license-headers → fmt → clippy → deny → test → build → examples → bench validate → docs).

---

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[mohamedmansour]

We cannot support this magic, I don't believe it is the right call. This will cause more maintenance overhead maintaining an allow list of attributes we don't want to propagate. This is like extending all the elements with the additional attributes they add to which doesn't conform with the w3c spec. In WebUI we are closely aligning to w3c spec, and all we are doing is an SSR for html elements with no magic.

Instead we need to build a plugin based solution where it allows the plugin to mutate the rendered element. Before you do that, we need to discuss in an issue regarding this topic.

[janechu]

We cannot support this magic, I don't believe it is the right call. This will cause more maintenance overhead maintaining an allow list of attributes we don't want to propagate. This is like extending all the elements with the additional attributes they add to which doesn't conform with the w3c spec. In WebUI we are closely aligning to w3c spec, and all we are doing is an SSR for html elements with no magic.

Instead we need to build a plugin based solution where it allows the plugin to mutate the rendered element. Before you do that, we need to discuss in an issue regarding this topic.

The issue shows up in the use of autofocus which requires a custom element has tabindex="0". If the initial page render does not include tabindex but does include autofocus then it won't autofocus.

I will say we are also scanning the template for shadowroot prefixed attributes and applying them to the template for DSD, I would put these problems in the same bucket.

Right now CSR works with reflecting attributes because it is fast enough, however that's just a quirk of the browser, in theory it should not work.

[janechu]

@mohamedmansour actually the reason it might be working in CSR is that we don't define the component until we have evaluated the template and applied attributes.

[janechu]

@mohamedmansour Thanks for the review — agreed completely on the 'magic in the parser core' concern. I've refactored to remove all FAST-specific knowledge from the WebUI parser. The parser now exposes three generic plugin extension points that any framework plugin can use to mutate the rendered custom-element opening tag and the inner <template> wrapper:

fn on_template_root_attributes(
    &mut self,
    tag_name: &str,
    attributes: &[TemplateRootAttribute],
) {}

fn host_element_attributes(
    &mut self,
    tag_name: &str,
    author_attr_names: &[&str],
) -> Option<String> { None }

fn template_element_attributes(&mut self, tag_name: &str) -> Option<String> { None }

What moved out of the parser core:

• Skip lists (@/:/? prefixes, f-ref/f-slotted/f-children, shadowroot*)
• Conflict normalization (:/? prefix stripping, @ preservation)
• The {{ ... }} dynamic-value skip
• The Shadow DOM gate

All of that now lives in a shared crates/webui-parser/src/plugin/fast_host_attrs.rs module used only by fast_v2 and fast_v3 plugins. The parser core only knows how to: capture structural attributes off a <template> root, hand them to the plugin once per tag, and splice plugin-supplied text into the host opening tag and the <template shadowrootmode="open"> wrapper with a single separator space.

Also fixed an ordering bug in the previous commit: on_template_root_attributes now fires before the host opening tag is emitted (previously, on a component's first usage, the propagation hook would have been called too late).

cargo xtask check passes locally (license-headers, fmt, clippy, deny, test, build, examples, bench validate, docs).