Document HTMLAllCollection (mdn#27974)

* Document HTMLAllCollection

* Apply suggestions from code review

Co-authored-by: wbamberg <[email protected]>

* Updates

---------

Co-authored-by: wbamberg <[email protected]>

files/en-us/web/api/document/all/index.md

@@ -10,10 +10,7 @@ browser-compat: api.Document.all
 
 {{APIRef("DOM")}}{{Deprecated_Header}}
 
-The {{DOMxRef("Document")}} interface's read-only **`all`**
-property returns an {{DOMxRef("HTMLAllCollection")}} rooted at the document node. In
-other words, it returns all of the document's elements, accessible by order (like an
-array) and by ID (like a regular object).
+The {{DOMxRef("Document")}} interface's read-only **`all`** property returns an {{DOMxRef("HTMLAllCollection")}} rooted at the document node.
 
 Rather than using `document.all` to return an {{DOMxRef("HTMLAllCollection")}} of all the document's elements in document order, you can use {{DOMxRef("Document.querySelectorAll")}} to return a {{DOMxRef("NodeList")}} of all the document's elements in document order:
 
@@ -25,30 +22,6 @@ const allElements = document.querySelectorAll("*");
 
 An {{DOMxRef("HTMLAllCollection")}} which contains every element in the document.
 
-## Special type conversion behavior
-
-For historical reasons, `document.all` is an object that in many ways behaves like `undefined`. Specifically:
-
-- It is [loosely equal](/en-US/docs/Web/JavaScript/Reference/Operators/Equality) to `undefined` and `null`.
-- It is [falsy](/en-US/docs/Glossary/Falsy) in boolean contexts.
-- Its [`typeof`](/en-US/docs/Web/JavaScript/Reference/Operators/typeof) is `"undefined"`.
-
-These special behaviors ensure that code like:
-
-```js
-if (document.all) {
-  // Assume that we are in IE; provide special logic
-}
-// Assume that we are in a modern browser
-```
-
-Will continue to provide modern behavior even if the code is run in a browser that implements `document.all` for compatibility reasons.
-
-However, in all other contexts, `document.all` remains an object. For example:
-
-- It is not [strictly equal](/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) to either `undefined` or `null`.
-- When used on the left-hand side of the [nullish coalescing operator](/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) (`??`) or the [optional chaining operator](/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) (`?.`), it will not cause the expression to short-circuit.
-
 ## Specifications
 
 {{Specifications}}

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

@@ -0,0 +1,70 @@
+---
+title: HTMLAllCollection
+slug: Web/API/HTMLAllCollection
+page-type: web-api-interface
+browser-compat: api.HTMLAllCollection
+---
+
+{{APIRef("DOM")}}{{Deprecated_Header}}
+
+The **`HTMLAllCollection`** interface represents a collection of _all_ of the document's elements, accessible by index (like an array) and by the element's [`id`](/en-US/docs/Web/HTML/Global_attributes/id). It is returned by the {{domxref("document.all")}} property.
+
+`HTMLAllCollection` has a very similar shape to {{domxref("HTMLCollection")}}, but there are many subtle behavior differences — for example, `HTMLAllCollection` can be called as a function, and its `item()` method can be called with a string representing an element's `id` or `name` attribute.
+
+## Instance properties
+
+- {{domxref("HTMLAllCollection.length")}} {{ReadOnlyInline}}
+  - : Returns the number of items in the collection.
+
+## Instance methods
+
+- {{domxref("HTMLAllCollection.item()")}}
+  - : Returns the element located at the specified offset into the collection, or the element with the specified value for its `id` or `name` attribute. Returns `null` if no element is found.
+- {{domxref("HTMLAllCollection.namedItem()")}}
+  - : Returns the first [element](/en-US/docs/Web/API/Element) in the collection whose [`id`](/en-US/docs/Web/HTML/Global_attributes/id) or `name` attribute match the given string name, or `null` if no element matches.
+
+## Usage in JavaScript
+
+### Indexed access
+
+In addition to the methods above, elements in an `HTMLAllCollection` can be accessed by integer indices and string property names. The HTML `id` attribute may contain `:` and `.` as valid characters, which would necessitate using bracket notation for property access. `collection[i]` is equivalent to `collection.item(i)`, where `i` can be an integer, a string containing an integer, or a string representing an `id`.
+
+### Calling as a function
+
+An `HTMLAllCollection` object is callable. When it's called with no arguments or with `undefined`, it returns `null`. Otherwise, it returns the same value as the {{domxref("HTMLAllCollection/item", "item()")}} method when given the same arguments.
+
+### Special type conversion behavior
+
+For historical reasons, `document.all` is an object that in the following ways behaves like `undefined`:
+
+- It is [loosely equal](/en-US/docs/Web/JavaScript/Reference/Operators/Equality) to `undefined` and `null`.
+- It is [falsy](/en-US/docs/Glossary/Falsy) in boolean contexts.
+- Its [`typeof`](/en-US/docs/Web/JavaScript/Reference/Operators/typeof) is `"undefined"`.
+
+These special behaviors ensure that code like:
+
+```js
+if (document.all) {
+  // Assume that we are in IE; provide special logic
+}
+// Assume that we are in a modern browser
+```
+
+Will continue to provide modern behavior even if the code is run in a browser that implements `document.all` for compatibility reasons.
+
+However, in all other contexts, `document.all` remains an object. For example:
+
+- It is not [strictly equal](/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) to either `undefined` or `null`.
+- When used on the left-hand side of the [nullish coalescing operator](/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) (`??`) or the [optional chaining operator](/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) (`?.`), it will not cause the expression to short-circuit.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("HTMLCollection")}}

files/en-us/web/api/htmlallcollection/item/index.md

@@ -0,0 +1,34 @@
+---
+title: "HTMLAllCollection: item() method"
+short-title: item()
+slug: Web/API/HTMLAllCollection/item
+page-type: web-api-instance-method
+browser-compat: api.HTMLAllCollection.item
+---
+
+{{APIRef("HTML DOM")}}
+
+The **`item()`** method of the {{domxref("HTMLAllCollection")}} interface returns the element located at the specified offset into the collection, or the element with the specified value for its `id` or `name` attribute.
+
+## Syntax
+
+```js-nolint
+item(nameOrIndex)
+```
+
+### Parameters
+
+- `nameOrIndex`
+  - : If this parameter is an integer, or a string that can be converted to an integer, then it represents the position of the {{domxref("Element")}} to be returned. Elements appear in an `HTMLAllCollection` in the same order in which they appear in the document's source. If the parameter is a string can't be converted to an integer, it will be interpreted as the `name` or `id` of the element to be returned.
+
+### Return value
+
+If `nameOrIndex` represents an index, `item()` returns the {{domxref("Element")}} at the specified index, or `null` if `nameOrIndex` is less than zero or greater than or equal to the length property. If `nameOrIndex` represents a name, `item()` returns the same value as {{domxref("HTMLAllCollection/namedItem", "namedItem()")}}.
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("HTMLCollection.item()")}}

files/en-us/web/api/htmlallcollection/length/index.md

@@ -0,0 +1,27 @@
+---
+title: "HTMLAllCollection: length property"
+short-title: length
+slug: Web/API/HTMLAllCollection/length
+page-type: web-api-instance-property
+browser-compat: api.HTMLAllCollection.length
+---
+
+{{APIRef("DOM")}}
+
+The **`HTMLAllCollection.length`** property returns the number of items in this {{domxref("HTMLAllCollection")}}.
+
+## Value
+
+An integer value representing the number of items in this `HTMLAllCollection`.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("HTMLCollection.length")}}

files/en-us/web/api/htmlallcollection/nameditem/index.md

@@ -0,0 +1,38 @@
+---
+title: "HTMLAllCollection: namedItem() method"
+short-title: namedItem()
+slug: Web/API/HTMLAllCollection/namedItem
+page-type: web-api-instance-method
+browser-compat: api.HTMLAllCollection.namedItem
+---
+
+{{APIRef("DOM")}}
+
+The **`namedItem()`** method of the {{domxref("HTMLAllCollection")}} interface returns the first {{domxref("Element")}} in the collection whose `id` or `name` attribute matches the specified name, or `null` if no element matches.
+
+## Syntax
+
+```js-nolint
+namedItem(name)
+```
+
+### Parameters
+
+- `name`
+  - : A string representing the value of the `id` or `name` attribute of the element we are looking for.
+
+### Return value
+
+The first {{domxref("Element")}} in the {{domxref("HTMLAllCollection")}} matching the `name`, or [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null), if there are none.
+
+## Specification
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("HTMLAllCollection.namedItem()")}}