feat: propagate shadowroot attributes (#7504)

# Pull Request

## 📖 Description

- Propagates `shadowroot*` attributes from `f-template` onto rendered declarative shadow DOM `<template>` elements.
- Preserves the existing default `shadowrootmode="open"` and `shadowroot="open"` behavior when no mode is provided.
- Updates FAST build configuration/docs and adds Rust/Node coverage for explicit, boolean, escaped, and extra shadowroot attributes.

## 👩‍💻 Reviewer Notes

Please focus review on the shadowroot attribute normalization/escaping path shared between the Rust renderer and the JS CLI configuration bridge.

## 📑 Test Plan

Passed:

- `git diff --check`
- `cargo test --manifest-path crates/microsoft-fast-build/Cargo.toml`
- `npm run build -w @microsoft/fast-build`
- `npm run test:node -w @microsoft/fast-build`
- `npm run build`
- `npm run biome:check`
- `npm run checkchange`

## ✅ Checklist

### General

- [ ] I have included a change request file using `$ npm run change`
- [x] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.

Author: janechu

change/@microsoft-fast-build-182ff259-711c-45c5-8be6-8925f2d78e79.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: propagate shadowroot attributes",
+  "packageName": "@microsoft/fast-build",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

change/@microsoft-fast-html-3b4bc9ff-fe92-4caa-a471-0f4895fe24b8.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat: propagate shadowroot attributes",
+  "packageName": "@microsoft/fast-html",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

crates/microsoft-fast-build/DESIGN.md

@@ -255,6 +255,8 @@ A custom element is any opening tag whose name contains a hyphen, excluding `f-w
      [light DOM children]
    </my-button>
    ```
+   The `<template>` receives any `shadowroot*` attributes declared on the source `<f-template>`. The renderer normalizes `shadowrootmode` and legacy `shadowroot` for compatibility: when neither has a non-empty value, it emits `shadowrootmode="open" shadowroot="open"`; when exactly one has a non-empty value, that value is mirrored to the other; when both have explicit non-empty values, both are preserved as authored, even if they conflict.
+
    When a nested element has attribute bindings (`{{expr}}` or `{expr}` values) and is being rendered inside another element's shadow (i.e., `parent_hydration` is `Some`), those bindings are counted, `data-fe-c-{start}-{count}` is added to the element's opening tag, and the binding indices are allocated from the parent scope.
 
 Note: `is_entry` controls only opening-tag attribute handling. Child state is always built using the current root state as a base with per-element attributes overlaid on top, regardless of the `is_entry` flag.
@@ -438,16 +440,17 @@ For each glob pattern:
 6. `<f-template>` elements missing a `name` attribute emit a warning to stderr and are ignored.
 7. If two `<f-template>` elements across different files share the same name → `RenderError::DuplicateTemplate`.
 
-### `<f-template>` parsing (`parse_f_templates`, `extract_attr_value`, `extract_template_content`)
+### `<f-template>` parsing (`parse_f_templates`, `parse_element_attributes`, `extract_template_content`)
 
 `parse_f_templates(html)` scans for `<f-template` occurrences using `str::find` in a loop. For each match:
 - Verifies the character after `<f-template` is not alphanumeric or `-` to avoid matching `<f-templateX>`.
 - Extracts the attribute string between `<f-template` and `>`.
-- Calls `extract_attr_value(attrs, "name")` to get the name (supports both `"` and `'` quoting).
+- Uses `parse_element_attributes` to get the `name` attribute value (supports both `"` and `'` quoting).
+- Collects all unique `shadowroot`-prefixed attributes from the `<f-template>` opening tag, preserving boolean attributes as `None` and lowercasing attribute names.
 - Extracts the inner HTML between `>` and `</f-template>`.
 - Calls `extract_template_content` on the inner HTML to get the content inside the `<template>` element.
 
-Returns `Vec<(Option<String>, String)>` — pairs of (name, template content).
+Returns a `Vec<FTemplate>` containing the optional name, template content, and the collected shadowroot attributes. The locator stores those attributes with the template definition so custom-element rendering can apply them to the emitted Declarative Shadow DOM `<template>`.
 
 ### Glob matching
 
@@ -477,12 +480,20 @@ Calls `locator::parse_f_templates` (the same function used by `Locator::from_pat
 
 ```json
 [
-  {"name": "my-button", "content": "<button>{{label}}</button>"},
-  {"name": null, "content": "<span>unnamed</span>"}
+  {
+    "name": "my-button",
+    "content": "<button>{{label}}</button>",
+    "shadowrootAttributes": [{"name": "shadowrootmode", "value": "closed"}]
+  },
+  {
+    "name": null,
+    "content": "<span>unnamed</span>",
+    "shadowrootAttributes": []
+  }
 ]
 ```
 
-`name` is `null` when the `<f-template>` element has no `name` attribute. The `@microsoft/fast-build` CLI uses this export to parse HTML files without reimplementing the parsing logic in JavaScript.
+`name` is `null` when the `<f-template>` element has no `name` attribute. The `shadowrootAttributes` array preserves forwarded `shadowroot*` attributes as `{name, value}` metadata, using `null` for boolean attributes. The `@microsoft/fast-build` CLI uses this export to parse HTML files without reimplementing the parsing logic in JavaScript.
 
 ### `render_with_templates`
 

crates/microsoft-fast-build/README.md

@@ -318,6 +318,8 @@ A single file may contain multiple templates:
 
 If an `<f-template>` element is missing a `name` attribute, a warning is emitted to stderr and the template is ignored.
 
+Any `shadowroot*` attributes on `<f-template>` are copied to the rendered Declarative Shadow DOM `<template>`. The renderer normalizes `shadowrootmode` and legacy `shadowroot` for compatibility: when neither has a non-empty value, it emits `shadowrootmode="open" shadowroot="open"`; when exactly one has a non-empty value, that value is mirrored to the other; when both have explicit non-empty values, both are preserved as authored, even if they conflict.
+
 ### Rendering with a Locator
 
 ```rust
@@ -465,7 +467,9 @@ The renderer wraps the rendered template in Declarative Shadow DOM and adds the
 </my-button>
 ```
 
+- `shadowrootmode="open"` — the standard declarative shadow DOM mode emitted by default.
 - `shadowroot="open"` — legacy declarative shadow DOM attribute for broader browser compatibility.
+- `shadowroot*` attributes declared on the source `<f-template>` are forwarded to the output `<template>`; `shadowrootmode` and `shadowroot` default to `open` when neither has a non-empty value, mirror when exactly one has a non-empty value, and are preserved as authored when both have explicit non-empty values.
 
 Custom elements that have no matching template in the locator are passed through verbatim.
 

crates/microsoft-fast-build/src/directive.rs

@@ -221,7 +221,7 @@ fn parse_repeat_expr(expr: &str) -> Option<(String, String)> {
 ///
 /// Output format:
 ///   `<original-open-tag>
-///    <template shadowrootmode="open" shadowroot="open">{rendered}</template>
+///    <template {shadowroot-attrs}>{rendered}</template>
 ///    {children}</{tag-name}>`
 ///
 /// For self-closing elements (`<my-button />`), the element is emitted as non-self-closing.
@@ -355,6 +355,7 @@ pub fn render_custom_element(
     let mut shadow_scope = HydrationScope::new();
     let element_template = locator.get_template(&tag_name).unwrap_or_default();
     let rendered = render_node(element_template, child_root, &[], Some(locator), Some(&mut shadow_scope), false, config)?;
+    let shadowroot_attributes = build_shadowroot_template_attrs(locator.get_shadowroot_attributes(&tag_name));
 
     // Build the final opening tag, resolving {{expr}} attrs and injecting hydration attrs.
     let element_open = build_element_open_tag(&open_tag_base, open_tag_content, root, loop_vars, parent_hydration, is_entry);
@@ -371,13 +372,83 @@ pub fn render_custom_element(
     };
 
     let output = format!(
-        "{}<template shadowrootmode=\"open\" shadowroot=\"open\">{}</template>{}</{}>",
-        element_open, rendered, children, tag_name
+        "{}<template{}>{}</template>{}</{}>",
+        element_open, shadowroot_attributes, rendered, children, tag_name
     );
 
     Ok((output, after))
 }
 
+fn build_shadowroot_template_attrs(attrs: &[(String, Option<String>)]) -> String {
+    let mut mode: Option<Option<String>> = None;
+    let mut legacy_shadowroot: Option<Option<String>> = None;
+    let mut forwarded: Vec<(String, Option<String>)> = Vec::new();
+    let mut seen_forwarded: Vec<String> = Vec::new();
+
+    for (name, value) in attrs {
+        let normalized = name.to_lowercase();
+        match normalized.as_str() {
+            "shadowrootmode" => {
+                if mode.is_none() {
+                    mode = Some(value.clone());
+                }
+            }
+            "shadowroot" => {
+                if legacy_shadowroot.is_none() {
+                    legacy_shadowroot = Some(value.clone());
+                }
+            }
+            _ if normalized.starts_with("shadowroot") => {
+                if !seen_forwarded.contains(&normalized) {
+                    seen_forwarded.push(normalized.clone());
+                    forwarded.push((normalized, value.clone()));
+                }
+            }
+            _ => {}
+        }
+    }
+
+    let explicit_mode = explicit_shadowroot_attr_value(mode);
+    let explicit_legacy_shadowroot = explicit_shadowroot_attr_value(legacy_shadowroot);
+    let mode = explicit_mode
+        .clone()
+        .or_else(|| explicit_legacy_shadowroot.clone())
+        .unwrap_or_else(|| "open".to_string());
+    let legacy_shadowroot = explicit_legacy_shadowroot
+        .or(explicit_mode)
+        .unwrap_or_else(|| mode.clone());
+
+    let mut out = String::new();
+    append_template_attr_value(&mut out, "shadowrootmode", &mode);
+    append_template_attr_value(&mut out, "shadowroot", &legacy_shadowroot);
+    for (name, value) in forwarded {
+        append_template_attr(&mut out, &name, &value);
+    }
+    out
+}
+
+fn explicit_shadowroot_attr_value(value: Option<Option<String>>) -> Option<String> {
+    value.flatten().filter(|value| !value.is_empty())
+}
+
+fn append_template_attr(out: &mut String, name: &str, value: &Option<String>) {
+    match value {
+        Some(value) => append_template_attr_value(out, name, value),
+        None => {
+            out.push(' ');
+            out.push_str(name);
+        }
+    }
+}
+
+fn append_template_attr_value(out: &mut String, name: &str, value: &str) {
+    out.push(' ');
+    out.push_str(name);
+    out.push_str("=\"");
+    out.push_str(&html_escape(value));
+    out.push('"');
+}
+
 fn attribute_to_json_value(value: Option<&String>, root: &JsonValue, loop_vars: &[(String, JsonValue)]) -> JsonValue {
     let v = match value {
         None => return JsonValue::Bool(true), // boolean attribute (no value)