Add shadowrootslotassignment attribute

files/en-us/web/api/element/attachshadow/index.md

@@ -97,10 +97,13 @@ attachShadow(options)
     - `slotAssignment` {{Optional_inline}}
       - : A string specifying the _slot assignment mode_ for the shadow DOM tree. This can be one of:
         - `named`
-          - : Elements are automatically assigned to {{HTMLElement("slot")}} elements within this shadow root. Any descendants of the host with a `slot` attribute which matches the `name` attribute of a `<slot>` within this shadow root will be assigned to that slot. Any top-level children of the host with no `slot` attribute will be assigned to a `<slot>` with no `name` attribute (the "default slot") if one is present.
+          - : Elements are automatically assigned to {{HTMLElement("slot")}} elements within this shadow root.
+            Any descendants of the host with a `slot` attribute which matches the `name` attribute of a `<slot>` within this shadow root will be assigned to that slot.
+            Any top-level children of the host with no `slot` attribute will be assigned to a `<slot>` with no `name` attribute (the "default slot") if one is present.
+            This is the default value.
         - `manual`
-          - : Elements are not automatically assigned to {{HTMLElement("slot")}} elements. Instead, they must be manually assigned with {{domxref("HTMLSlotElement.assign()")}}.
-            Its default value is `named`.
+          - : Elements are manually assigned to particular slot elements using {{domxref("HTMLSlotElement.assign()")}}.
+            No automatic assignment takes place.
 
 ### Return value
 
@@ -191,6 +194,119 @@ class MyCustomElement extends HTMLElement {
 customElements.define("my-custom-element", MyCustomElement);
 ```
 
+### Shadow DOM with named slot assignment
+
+This example demonstrates named slot assignment.
+
+#### Feature checking
+
+This part of the example defines a warning that will indicate if the type of slot assignment can be changed.
+
+First we create HTML that displays the warning if the mechanism is not supported.
+
+```html
+<p id="support-warning" hidden>
+  ⛔ Your browser doesn't support setting slot assignment (named assignment is
+  used).
+</p>
+```
+
+This code tests if the {{domxref("ShadowRoot.slotAssignment")}} property is defined, and uses the result to display the warning if it is not.
+
+```js
+const isSlotAssignmentSupported = Object.hasOwn(
+  ShadowRoot.prototype,
+  "slotAssignment",
+);
+
+document
+  .querySelector("p[hidden]")
+  .toggleAttribute("hidden", isSlotAssignmentSupported);
+```
+
+#### Creating the web component
+
+This code creates a web component that has three named slots for an article's title, metadata, and body section.
+The ShadowRoot is created with `slotAssignment: "named"`.
+
+```js
+class MyArticle extends HTMLElement {
+  constructor() {
+    super();
+    // Attach the shadow root specifying that slotAssignment is "named" (not manual)
+    this.attachShadow({ mode: "open", slotAssignment: "named" });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  render() {
+    // Define the internal structure and styles
+    this.shadowRoot.innerHTML = `
+      <style>
+        .header {
+          background-color: plum;
+        }
+        .meta {
+          background-color: green;
+        }
+        .body {
+          background-color: lightblue;
+        }
+      </style>
+
+      <h2 class="header">
+        <slot name="title"></slot>
+      </h2>
+
+      <div class="meta">
+        <slot name="meta"></slot>
+      </div>
+
+      <div class="body">
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+// Register the component
+customElements.define("my-article", MyArticle);
+```
+
+#### Using the web component
+
+The HTML below uses the `<my-article>` web component we just created.
+The nested elements are rendered in the component's slots based on name matching.
+The unnamed elements are rendered in the component's unnamed slot (the body).
+
+```html
+<my-article>
+  <span slot="title">Text for the title slot</span>
+  <span slot="meta">Text for the meta slot</span>
+
+  <p>
+    Text 1 with no slot attribute. Goes into default (unnamed) slot inside the
+    "body" div.
+  </p>
+  <p>
+    Text 2 with no slot attribute. Also goes into default (unnamed) slot inside
+    the "body" div.
+  </p>
+</my-article>
+```
+
+#### Results
+
+The example below should show the content of the slots displayed in the appropriate sections.
+
+{{EmbedLiveSample('Shadow DOM with named slot assignment','100', '220px')}}
+
+> [!NOTE]
+> The example will still work even if the warning is displayed that shadow root slot assignment is not supported.
+> This is because `named` assignment predates the introduction of the `slotAssignment` property.
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/htmltemplateelement/index.md

@@ -32,6 +32,8 @@ _This interface inherits the properties of {{domxref("HTMLElement")}}._
   - : A string that reflects the value of the [`shadowrootcustomelementregistry`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootcustomelementregistry) attribute of the associated `<template>` element, indicating that the declarative shadow root will use a scoped {{domxref("CustomElementRegistry")}}.
 - {{domxref("HTMLTemplateElement.shadowRootSerializable", "shadowRootSerializable")}}
   - : A boolean that reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootserializable) attribute of the associated `<template>` element.
+- {{domxref("HTMLTemplateElement.shadowRootSlotAssignment", "shadowRootSlotAssignment")}}
+  - : A string that reflects the value of the [`shadowrootslotassignment`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) attribute of the associated `<template>` element.
 
 ## Instance methods
 

files/en-us/web/api/htmltemplateelement/shadowrootslotassignment/index.md

@@ -0,0 +1,48 @@
+---
+title: "HTMLTemplateElement: shadowRootSlotAssignment property"
+short-title: shadowRootSlotAssignment
+slug: Web/API/HTMLTemplateElement/shadowRootSlotAssignment
+page-type: web-api-instance-property
+browser-compat: api.HTMLTemplateElement.shadowRootSlotAssignment
+---
+
+{{APIRef("Web Components")}}
+
+The **`shadowRootSlotAssignment`** property of the {{domxref("HTMLTemplateElement")}} interface reflects the value of the [`shadowrootslotassignment`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element.
+
+This property can be used to detect support for the declarative attribute.
+
+The property has no other purpose for developers:
+
+- If a `<template>` element is used to declaratively create a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot), then no instance of this object and property exist.
+- If an `HTMLTemplateElement` is created, the value of this property is irrelevant because the object is not a shadow root and cannot subsequently be changed to a shadow root.
+
+## Value
+
+A string that reflects the value of the [`shadowrootslotassignment`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. Possible values are `"named"` and `"manual"`.
+
+## Example
+
+### Basic usage
+
+This code shows how you can check if the [`shadowrootslotassignment`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) attribute is supported on {{htmlelement("template")}} elements.
+
+```js
+const isShadowRootSlotAssignmentSupported = Object.hasOwn(
+  HTMLTemplateElement.prototype,
+  "shadowRootSlotAssignment",
+);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`shadowrootslotassignment`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) attribute of the `<template>` element
+- [`ShadowRoot.slotAssignment`](/en-US/docs/Web/API/ShadowRoot/slotAssignment)

files/en-us/web/api/shadowroot/slotassignment/index.md

@@ -8,20 +8,29 @@ browser-compat: api.ShadowRoot.slotAssignment
 
 {{APIRef("Shadow DOM")}}
 
-The read-only **`slotAssignment`** property of the {{domxref("ShadowRoot")}} interface returns the _slot assignment mode_ for the shadow DOM tree. Nodes are either automatically assigned (`named`) or manually assigned (`manual`). The value of this property defined using the `slotAssignment` option when calling {{domxref("Element.attachShadow()")}}.
+The read-only **`slotAssignment`** property of the {{domxref("ShadowRoot")}} interface returns the _slot assignment mode_ for the shadow DOM tree. Nodes are either automatically assigned based on name matching (`named`) or manually assigned (`manual`).
+
+The value of this property is defined using the `slotAssignment` option when calling {{domxref("Element.attachShadow()")}}, or using the [`shadowrootslotassignment`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) attribute on {{htmlelement("template")}} when declaratively creating a shadow root.
 
 ## Value
 
 A string that can be one of:
 
 - `named`
-  - : Elements are automatically assigned to {{HTMLElement("slot")}} elements within this shadow root. Any descendants of the host with a `slot` attribute which matches the `name` attribute of a `<slot>` within this shadow root will be assigned to that slot. Any top-level children of the host with no `slot` attribute will be assigned to a `<slot>` with no `name` attribute (the "default slot") if one is present.
+  - : Elements are automatically assigned to {{HTMLElement("slot")}} elements within this shadow root.
+    Any descendants of the host with a `slot` attribute which matches the `name` attribute of a `<slot>` within this shadow root will be assigned to that slot.
+    Any top-level children of the host with no `slot` attribute will be assigned to a `<slot>` with no `name` attribute (the "default slot") if one is present.
 - `manual`
-  - : Elements are not automatically assigned to {{HTMLElement("slot")}} elements. Instead, they must be manually assigned with {{domxref("HTMLSlotElement.assign()")}}.
+  - : Elements are not automatically assigned to {{HTMLElement("slot")}} elements.
+    Instead, they must be manually assigned with {{domxref("HTMLSlotElement.assign()")}}.
 
 ## Examples
 
-In the example below, the `assign()` method is used to display the correct tab in a tabbed application. The function is called and passed the panel to show, which is then assigned to the slot. We test if the `slotAssignment` is `named` to prevent an exception to be raised when {{domxref("HTMLSlotElement.assign()")}} is called.
+### Basic usage
+
+In the example below, the `assign()` method is used to display the correct tab in a tabbed application.
+The function is called and passed the panel to show, which is then assigned to the slot.
+We test if the `slotAssignment` is `named` to prevent an exception to be raised when {{domxref("HTMLSlotElement.assign()")}} is called.
 
 ```js
 function UpdateDisplayTab(elem, tabIdx) {
@@ -55,3 +64,5 @@ function UpdateDisplayTab(elem, tabIdx) {
 
 - {{domxref("Element.attachShadow()")}}
 - {{domxref("HTMLSlotElement.assign()")}}
+- [`shadowrootslotassignment`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) attribute of the `<template>` element
+- {{domxref("HTMLTemplateElement.shadowRootSlotAssignment")}}

files/en-us/web/html/reference/elements/slot/index.md

@@ -14,7 +14,15 @@ The **`<slot>`** [HTML](/en-US/docs/Web/HTML) element—part of the [Web Compone
 This element includes the [global attributes](/en-US/docs/Web/HTML/Reference/Global_attributes).
 
 - `name`
-  - : The slot's name. When the slot's containing component gets rendered, the slot is rendered with the custom element's child that has a matching [`slot`](/en-US/docs/Web/HTML/Reference/Global_attributes/slot) attribute. A _named slot_ is a `<slot>` element with a `name` attribute. Unnamed slots have the name default to the empty string. Names should be unique per shadow root: if you have two slots with the same name, all of the elements with a matching `slot` attribute will be assigned to the first slot with that name.
+  - : The slot's name.
+    A _named slot_ is a `<slot>` element with a `name` attribute, while unnamed slots have no `name` attribute, and the name defaults to the empty string.
+
+    When the associated shadow root uses [named slot assignment](/en-US/docs/Web/HTML/Reference/Elements/template#named), the slot's containing element is rendered with elements in the same host that have a [`slot` attribute](/en-US/docs/Web/API/Element/slot) with the same name.
+    All elements that don't have a `slot` attribute are rendered in the first unnamed `<slot>` element, which is referred to as the _default slot_.
+    Slot names should be unique per shadow root: if you have two slots with the same name, all of the elements with a matching `slot` attribute will be assigned to the first slot with that name.
+    The `name` has no effect if [manual slot assignment](/en-US/docs/Web/HTML/Reference/Elements/template#manual) is used.
+
+    For more information see [`shadowrootslotassignment`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) on the `<template>` element and [`Element.attachShadow()`](/en-US/docs/Web/API/Element/attachShadow#slotassignment).
 
 ## Examples
 
@@ -71,26 +79,17 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Reference/Glo
   <tbody>
     <tr>
       <th scope="row">
-        <a href="/en-US/docs/Web/HTML/Guides/Content_categories"
-          >Content categories</a
-        >
+        <a href="/en-US/docs/Web/HTML/Guides/Content_categories">Content categories</a>
       </th>
       <td>
-        <a href="/en-US/docs/Web/HTML/Guides/Content_categories#flow_content"
-          >Flow content</a
-        >,
-        <a href="/en-US/docs/Web/HTML/Guides/Content_categories#phrasing_content"
-          >phrasing content</a
-        >
+        <a href="/en-US/docs/Web/HTML/Guides/Content_categories#flow_content">Flow content</a>,
+        <a href="/en-US/docs/Web/HTML/Guides/Content_categories#phrasing_content">phrasing content</a>
       </td>
     </tr>
     <tr>
       <th scope="row">Permitted content</th>
       <td>
-        <a
-          href="/en-US/docs/Web/HTML/Guides/Content_categories#transparent_content_model"
-          >Transparent</a
-        >
+        <a href="/en-US/docs/Web/HTML/Guides/Content_categories#transparent_content_model">Transparent</a>
       </td>
     </tr>
     <tr>
@@ -104,18 +103,13 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Reference/Glo
     <tr>
       <th scope="row">Permitted parents</th>
       <td>
-        Any element that accepts
-        <a href="/en-US/docs/Web/HTML/Guides/Content_categories#phrasing_content"
-          >phrasing content</a
-        >
+        Any element that accepts <a href="/en-US/docs/Web/HTML/Guides/Content_categories#phrasing_content">phrasing content</a>
       </td>
     </tr>
     <tr>
       <th scope="row">Implicit ARIA role</th>
       <td>
-        <a href="https://w3c.github.io/html-aria/#dfn-no-corresponding-role"
-          >No corresponding role</a
-        >
+        <a href="https://w3c.github.io/html-aria/#dfn-no-corresponding-role">No corresponding role</a>
       </td>
     </tr>
     <tr>