New pages: htmloptionscollection (#35982)

* New pages: htmloptionscollection

* remove refect word

* Apply suggestions from code review

Co-authored-by: Joshua Chen <[email protected]>

* edits per review

* Update index.md

* Update files/en-us/web/api/htmloptionscollection/selectedindex/index.md

---------

Co-authored-by: Joshua Chen <[email protected]>

files/en-us/web/api/htmloptionscollection/add/index.md

@@ -0,0 +1,67 @@
+---
+title: "HTMLOptionsCollection: add() method"
+short-title: add()
+slug: Web/API/HTMLOptionsCollection/add
+page-type: web-api-instance-method
+browser-compat: api.HTMLOptionsCollection.add
+---
+
+{{APIRef("HTML DOM")}}
+
+The **`add()`** method of the {{DOMxRef("HTMLOptionsCollection")}} interface adds an {{domxref("HTMLOptionElement")}} or {{domxref("HTMLOptGroupElement")}} to this `HTMLOptionsCollection`.
+
+## Syntax
+
+```js-nolint
+add(item)
+add(item, before)
+```
+
+### Parameters
+
+- `item`
+  - : An {{domxref("HTMLOptionElement")}} or {{domxref("HTMLOptGroupElement")}}.
+- `before` {{optional_inline}}
+  - : An element of the collection, or a numeric 0-based index representing the element that the `item` should be inserted before. If omitted, `null`, or the index does not exist, the new element is appended to the end of the collection.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+### Exceptions
+
+- `HierarchyRequestError` {{DOMxRef("DOMException")}}
+  - : Thrown if the `item` passed to the method is an ancestor of the element into which it is to be inserted.
+
+## Description
+
+By default, the `add()` appends the {{HTMLelement("option")}} or {{HTMLelement("optgroup")}} passed as the parameter to the end of the collection. You can define where the added `<option>` or `<optgroup>` should be placed by specifying the `before` parameter. The `before` is the `<option>` element or a numeric `0`-based index of the `<option>` element the added element should precede.
+
+If the `before` parameter is null or out of range (or omitted), the `<option>` or `<optgroup>` will be appended as the last element in the collection, outside of any {{HTMLelement("optgroup")}}. If the `<option>` referenced by the `before` parameter is in an {{HTMLelement("optgroup")}}, an added `HTMLOptionElement` will be in the same group.
+
+The `<optgroup>` element can only contain `<option>` elements as child nodes. The `add()` method will successfully add an `HTMLOptGroupElement` to the end of the `HTMLOptionsCollection` or between `<optgroup>` elements only. In other words, attempting to add an `HTMLOptGroupElement` before an `<option>` within an `<optgroup>` may silently fail if the `<option>` referenced by the `before` parameter is not the first `<option>` within its `<optgroup>`.
+
+## Examples
+
+```js
+const optionList = document.querySelector("select").options;
+const firstOption = document.createElement("option");
+firstOption.text = "new item";
+optionList.add(firstOption, 0); // added as the first item
+optionList.add(optionList[0]); // moves the first item to the end
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{HTMLElement("select")}}
+- {{DOMxRef("HTMLOptionsCollection.remove")}}
+- {{DOMxRef("HTMLOptionsCollection.length")}}
+- {{DOMxRef("HTMLOptionsCollection.selectedIndex")}}

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

@@ -13,13 +13,20 @@ The **`HTMLOptionsCollection`** interface represents a collection of [`<option>`
 
 ## Instance properties
 
-- `length`
-  - : `unsigned long`. As optionally allowed by the spec, this property isn't read-only. You can either remove options from the end by lowering the value, or add blank options at the end by raising the value. Mozilla allows this, while other implementations could potentially throw a [DOMException](/en-US/docs/Web/API/DOMException).
+- {{domxref("HTMLOptionsCollection.length")}}
+  - : Returns or sets the number of options in the collection.
+- {{domxref("HTMLOptionsCollection.selectedIndex")}}
+  - : The index number of the first selected {{HTMLElement("option")}} element. The value `-1` indicates no element is selected.
 
 ## Instance methods
 
 _This interface inherits the methods of its parent, [`HTMLCollection`](/en-US/docs/Web/API/HTMLCollection)._
 
+- {{domxref("HTMLOptionsCollection.add()")}}
+  - : Appends an {{domxref("HTMLOptionElement")}} or {{domxref("HTMLOptGroupElement")}} element to the collection of `option` elements or adds it before a specified option.
+- {{domxref("HTMLOptionsCollection.remove()")}}
+  - : Removes the element at the specified index from the options collection.
+
 ## Specifications
 
 {{Specifications}}
@@ -32,4 +39,6 @@ _This interface inherits the methods of its parent, [`HTMLCollection`](/en-US/do
 
 - {{DOMxRef("HTMLOptionElement")}}
 - {{DOMxRef("HTMLCollection")}}
+- {{DOMxRef("HTMLOptGroupElement")}}
+- {{DOMxRef("HTMLSelectElement")}}
 - [Indexed collections guide](/en-US/docs/Web/JavaScript/Guide/Indexed_collections)

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

@@ -0,0 +1,43 @@
+---
+title: "HTMLOptionsCollection: length property"
+short-title: length
+slug: Web/API/HTMLOptionsCollection/length
+page-type: web-api-instance-property
+browser-compat: api.HTMLOptionsCollection.length
+---
+
+{{APIRef("DOM")}}
+
+The **`length`** property of the {{DOMxRef("HTMLOptionsCollection")}} interface returns the number of {{htmlelement("option")}} elements in the collection. The property can get or set the size of the collection.
+
+When setting `length` to a value smaller than the current, the options collection gets truncated; otherwise, new blank `<option>` elements are appended to the end of the `<select>`.
+
+## Value
+
+An integer value representing the number of items in this `HTMLOptionsCollection`.
+
+## Example
+
+```js
+const optCollection = document.getElementById("fruits").options;
+const origLength = optCollection.length;
+optCollection.length += 50; // adds 50 blank options to the collection
+optCollection.length = origLength; // truncates the list back to the original size
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{DOMxRef("HTMLOptionsCollection.add()")}}
+- {{DOMxRef("HTMLOptionsCollection.remove()")}}
+- {{DOMxRef("HTMLOptionsCollection.selectedIndex")}}
+- {{domxref("HTMLSelectElement") }}
+- {{domxref("HTMLOptGroupElement")}}
+- {{domxref("HTMLCollection.length")}}

files/en-us/web/api/htmloptionscollection/remove/index.md

@@ -0,0 +1,52 @@
+---
+title: "HTMLOptionsCollection: remove() method"
+short-title: remove()
+slug: Web/API/HTMLOptionsCollection/remove
+page-type: web-api-instance-method
+browser-compat: api.HTMLOptionsCollection.remove
+---
+
+{{ APIRef("HTML DOM") }}
+
+The **`remove()`** method of the {{DOMxRef("HTMLOptionsCollection")}} interface removes the {{HTMLelement("option")}} element specified by the index from this collection.
+
+## Syntax
+
+```js-nolint
+remove(index)
+```
+
+### Parameters
+
+- `index`
+  - : A zero-based integer for the index of the {{ domxref("HTMLOptionElement") }} in the {{DOMxRef("HTMLOptionsCollection")}}. If the index is not found the method has no effect.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Examples
+
+```js
+const optionList = document.querySelector("select").options;
+const listLength = optionList.length;
+optionList.remove(listLength - 1); // removes the last item
+optionList.remove(0); // removes the first item
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{DOMxRef("HTMLOptionsCollection.add")}}
+- {{DOMxRef("HTMLOptionsCollection.length")}}
+- {{DOMxRef("HTMLOptionsCollection.selectedIndex")}}
+- {{domxref("HTMLOptionsCollection") }}
+- {{domxref("HTMLOptionsCollection.remove()")}}
+- {{domxref("Element.remove")}}

files/en-us/web/api/htmloptionscollection/selectedindex/index.md

@@ -0,0 +1,42 @@
+---
+title: "HTMLOptionsCollection: selectedIndex property"
+short-title: selectedIndex
+slug: Web/API/HTMLOptionsCollection/selectedIndex
+page-type: web-api-instance-property
+browser-compat: api.HTMLOptionsCollection.selectedIndex
+---
+
+{{APIRef("HTML DOM")}}
+
+The **`selectedIndex`** property of the {{DOMxRef("HTMLOptionsCollection")}} interface is the numeric index of the first selected {{HTMLElement("option")}} element, if any, or `−1` if no `<option>` is selected. Setting this property selects the option at that index and deselects all other options in this collection, while setting it to `-1` deselects any currently selected elements. It is exactly equivalent to the {{domxref("HTMLSelectElement.selectedIndex", "selectedIndex")}} property of the {{domxref("HTMLSelectElement")}} that owns this collection.
+
+## Value
+
+A number.
+
+## Examples
+
+```js
+const optionColl = document.getElementById("select").options;
+console.log(`selected option: ${optionColl.selectedIndex}`); // the index of the first selected option, or -1 if no option is selected
+optionColl.selectedIndex = 0; // selects the first item
+optionColl.selectedIndex = -1; // deselects any selected option
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{DOMxRef("HTMLOptionsCollection.length")}}
+- {{DOMxRef("HTMLOptionsCollection.add()")}}
+- {{DOMxRef("HTMLOptionsCollection.remove()")}}
+- {{DOMxRef("HTMLOptionsCollection")}}
+- {{DOMxRef("HTMLOptionElement")}}
+- {{DOMxRef("HTMLOptGroupElement")}}
+- {{DOMxRef("HTMLSelectElement")}}

files/en-us/web/api/htmlselectelement/selectedindex/index.md

@@ -8,10 +8,7 @@ browser-compat: api.HTMLSelectElement.selectedIndex
 
 {{APIRef("HTML DOM")}}
 
-The **`HTMLSelectElement.selectedIndex`** property is a
-`long` that reflects the index of the first or last selected
-{{HTMLElement("option")}} element, depending on the value of `multiple`. The
-value `-1` indicates that no element is selected.
+The **`selectedIndex`** property of the {{DOMxRef("HTMLSelectElement")}} interface is the numeric index of the first selected {{HTMLElement("option")}} element in a {{HTMLElement("select")}} element, if any, or `−1` if no `<option>` is selected. Setting this property selects the option at that index and deselects all other options, while setting it to `-1` deselects any currently selected options.
 
 ## Value