Document ShadowRoot.slotAssignment (#25649)

* Document ShadowRoot.slotAssignment

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

Co-authored-by: Ruth John <Rumyra@users.noreply.github.com>

---------

Co-authored-by: Ruth John <Rumyra@users.noreply.github.com>

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

@@ -14,7 +14,7 @@ The **`Element.attachShadow()`** method attaches a shadow DOM tree to the specif
 Note that you can't attach a shadow root to every type of element.
 There are some that can't have a shadow DOM for security reasons (for example {{htmlelement("a")}}).
 
-The following is a list of elements you **can** attach a shadow root to:
+The following is a list of elements you _can_ attach a shadow root to:
 
 - Any autonomous custom element with a [valid name](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name)
 - {{htmlelement("article")}}
@@ -73,13 +73,20 @@ attachShadow(options)
             element.shadowRoot; // Returns null
             ```
 
-    - `delegatesFocus`
+    - `delegatesFocus` {{Optional_Inline}}
 
       - : A boolean that, when set to `true`, specifies behavior that mitigates custom element issues around focusability.
-        When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available `:focus` styling.
+        When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available `:focus` styling. Its default value is `false`.
 
-    - `slotAssignment`
-      - : Either `manual` or `named` (default). When set to `manual`, use {{DOMxRef("HTMLSlotElement.assign()")}} to assign a value to `slot`.
+    - `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 descendents 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()")}}.
+            Its default value is `named`.
 
 ### Return value
 
@@ -150,4 +157,6 @@ customElements.define("word-count", WordCount, { extends: "p" });
 
 ## See also
 
+- {{domxref("ShadowRoot.mode")}}
 - {{domxref("ShadowRoot.delegatesFocus")}}
+- {{domxref("ShadowRoot.slotAssignment")}}

files/en-us/web/api/htmlslotelement/assign/index.md

@@ -7,10 +7,9 @@ browser-compat: api.HTMLSlotElement.assign
 
 {{APIRef("Shadow DOM API")}}
 
-The **`assign()`** method of the
-{{domxref("HTMLSlotElement")}} interface sets the slot's **manually assigned nodes** to an ordered set of slottables. The manually assigned nodes set is initially empty until nodes are assigned using `assign()`.
+The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets the slot's _manually assigned nodes_ to an ordered set of slottables. The manually assigned nodes set is initially empty until nodes are assigned using `assign()`.
 
-Please note that you cannot mix declarative and imperative slot assignment. Therefore, for this to work, the shadow tree needs to have been created with the `slotAssignment: "manual"` option.
+> **Note:** you cannot mix manually (imperative) and named (declarative, automatic) slot assignments. Therefore, for this method to work, the shadow tree needs to have been [created](/en-US/docs/Web/API/Element/attachShadow) with the `slotAssignment: "manual"` option.
 
 ## Syntax
 
@@ -27,11 +26,16 @@ assign(node1, node2, /* … ,*/ nodeN)
 
 ### Return value
 
-Undefined.
+None ({{jsxref("undefined")}}).
+
+### Exceptions
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  -: Thrown when calling this method on an automatically assigned slot.
 
 ## Examples
 
-In the below example, 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.
+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.
 
 ```js
 function UpdateDisplayTab(elem, tabIdx) {
@@ -53,3 +57,7 @@ function UpdateDisplayTab(elem, tabIdx) {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("Element.attachShadow()")}}

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

@@ -29,13 +29,15 @@ You can retrieve a reference to an element's shadow root using its {{domxref("El
 - {{domxref("ShadowRoot.innerHTML")}}
   - : Sets or returns a reference to the DOM tree inside the `ShadowRoot`.
 - {{domxref("ShadowRoot.mode")}} {{ReadOnlyInline}}
-  - : The mode of the `ShadowRoot` — either `open` or `closed`.
+  - : The mode of the `ShadowRoot`, either `open` or `closed`.
     This defines whether or not the shadow root's internal features are accessible from JavaScript.
 - {{DOMxRef("ShadowRoot.pictureInPictureElement")}} {{ReadOnlyInline}}
   - : Returns the {{DOMxRef('Element')}} within the shadow tree that is currently being presented in picture-in-picture mode.
 - {{DOMxRef("ShadowRoot.pointerLockElement")}} {{ReadOnlyInline}}
   - : Returns the {{DOMxRef('Element')}} set as the target for mouse events while the pointer is locked.
     `null` if lock is pending, pointer is unlocked, or if the target is in another tree.
+- {{DOMxRef("ShadowRoot.slotAssignment")}} {{ReadOnlyInline}}
+  - : Returns a string containing the type of slot assignement, either `manual` or `named`.
 - {{domxref("ShadowRoot.styleSheets")}} {{ReadOnlyInline}}
   - : Returns a {{domxref('StyleSheetList')}} of {{domxref('CSSStyleSheet')}} objects for stylesheets explicitly linked into, or embedded in a shadow tree.
 

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

@@ -0,0 +1,56 @@
+---
+title: ShadowRoot.slotAssignment
+slug: Web/API/ShadowRoot/slotAssignment
+page-type: web-api-instance-property
+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()")}}.
+
+## Value
+
+A string that can be one of:
+
+- `named`
+  - : Elements are automatically assigned to {{HTMLElement("slot")}} elements within this shadow root. Any descendents 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()")}}.
+
+## 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.
+
+```js
+function UpdateDisplayTab(elem, tabIdx) {
+  const shadow = elem.shadowRoot;
+
+  // This test is usually not needed, but can be useful when debugging
+  if (shadow.slotAssignment === "named") {
+    console.error(
+      "Trying to manually assign a slot on an automatically-assigned (named) slot"
+    );
+  }
+  const slot = shadow.querySelector("slot");
+  const panels = elem.querySelectorAll("tab-panel");
+  if (panels.length && tabIdx && tabIdx <= panels.length) {
+    slot.assign(panels[tabIdx - 1]);
+  } else {
+    slot.assign();
+  }
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Element.attachShadow()")}}
+- {{domxref("HTMLSlotElement.assign()")}}