Merge pull request #599 from scala-js/topic/html-collection

japgolly · web-flow · commit 8a2d8f6cfec6 · 2021-10-17T20:25:00.000+11:00
Improve `HTMLCollection` and friends
diff --git a/api-reports/2_12.txt b/api-reports/2_12.txt
diff --git a/api-reports/2_13.txt b/api-reports/2_13.txt
diff --git a/src/main/scala/org/scalajs/dom/Document.scala b/src/main/scala/org/scalajs/dom/Document.scala
@@ -51,18 +51,18 @@ abstract class Document extends Node with NodeSelector with DocumentEvent with P
     * root node. The returned HTMLCollection is live, meaning that it updates itself automatically to stay in sync with
     * the DOM tree without having to call document.getElementsByTagName again.
     */
-  def getElementsByTagName(name: String): HTMLCollection = js.native
+  def getElementsByTagName(name: String): HTMLCollection[Element] = js.native
 
   /** Returns a list of elements with the given tag name belonging to the given namespace. The complete document is
     * searched, including the root node.
     */
-  def getElementsByTagNameNS(namespaceURI: String, localName: String): HTMLCollection = js.native
+  def getElementsByTagNameNS(namespaceURI: String, localName: String): HTMLCollection[Element] = js.native
 
   /** Returns a set of elements which have all the given class names. When called on the document object, the complete
     * document is searched, including the root node. You may also call getElementsByClassName on any element; it will
     * return only elements which are descendants of the specified root element with the given class names.
     */
-  def getElementsByClassName(classNames: String): HTMLCollection = js.native
+  def getElementsByClassName(classNames: String): HTMLCollection[Element] = js.native
 
   /** Returns the element from the document whose elementFromPoint method is being called which is the topmost element
     * which lies under the given point.  To get an element, specify the point via coordinates, in CSS pixels, relative
diff --git a/src/main/scala/org/scalajs/dom/Element.scala b/src/main/scala/org/scalajs/dom/Element.scala
@@ -167,17 +167,17 @@ abstract class Element extends Node with NodeSelector with ParentNode with NonDo
     * automatically. Consequently, there is no need to call several times element.getElementsByTagName with the same
     * element and arguments.
     */
-  def getElementsByTagName(name: String): HTMLCollection = js.native
+  def getElementsByTagName(name: String): HTMLCollection[Element] = js.native
 
   /** Returns a list of elements with the given tag name belonging to the given namespace. */
-  def getElementsByTagNameNS(namespaceURI: String, localName: String): HTMLCollection = js.native
+  def getElementsByTagNameNS(namespaceURI: String, localName: String): HTMLCollection[Element] = js.native
 
   /** Returns an array-like object of all child elements which have all of the given class names. When called on the
     * document object, the complete document is searched, including the root node. You may also call
     * getElementsByClassName() on any element; it will return only elements which are descendants of the specified root
     * element with the given class names.
     */
-  def getElementsByClassName(classNames: String): HTMLCollection = js.native
+  def getElementsByClassName(classNames: String): HTMLCollection[Element] = js.native
 
   /** hasAttributeNS returns a boolean value indicating whether the current element has the specified attribute. */
   def hasAttributeNS(namespaceURI: String, localName: String): Boolean = js.native
diff --git a/src/main/scala/org/scalajs/dom/HTMLCollection.scala b/src/main/scala/org/scalajs/dom/HTMLCollection.scala
@@ -14,12 +14,12 @@ import scala.scalajs.js.annotation._
   */
 @js.native
 @JSGlobal
-class HTMLCollection private[this] () extends DOMList[Element] {
-  def item(index: Int): Element = js.native
+abstract class HTMLCollection[+E] extends DOMList[E] {
+  def item(index: Int): E = js.native
 
   /** Returns the specific node whose ID or, as a fallback, name matches the string specified by name. Matching by name
     * is only done as a last resort, only in HTML, and only if the referenced element supports the name attribute.
     * Returns null if no node exists by the given name.
     */
-  def namedItem(name: String): Element = js.native
+  def namedItem(name: String): E = js.native
 }
diff --git a/src/main/scala/org/scalajs/dom/HTMLDataListElement.scala b/src/main/scala/org/scalajs/dom/HTMLDataListElement.scala
@@ -17,5 +17,5 @@ import scala.scalajs.js.annotation._
 abstract class HTMLDataListElement extends HTMLElement {
 
   /** A collection of the contained option elements. */
-  def options: HTMLCollection = js.native
+  def options: HTMLCollection[Element] = js.native
 }
diff --git a/src/main/scala/org/scalajs/dom/HTMLDocument.scala b/src/main/scala/org/scalajs/dom/HTMLDocument.scala
@@ -68,26 +68,26 @@ abstract class HTMLDocument extends Document {
   def activeElement: Element = js.native
 
   /** Returns a list of the embedded &lt;embed&gt; elements within the current document. */
-  def embeds: HTMLCollection = js.native
+  def embeds: HTMLCollection[Element] = js.native
 
   /** forms returns a collection (an HTMLCollection) of the form elements within the current document. */
-  def forms: HTMLCollection = js.native
+  def forms: HTMLCollection[Element] = js.native
 
   /** The links property returns a collection of all AREA elements and anchor elements in a document with a value for
     * the href attribute.
     */
-  def links: HTMLCollection = js.native
+  def links: HTMLCollection[Element] = js.native
 
   /** anchors returns a list of all of the anchors in the document. */
-  def anchors: HTMLCollection = js.native
+  def anchors: HTMLCollection[Element] = js.native
 
   /** Returns an HTMLCollection object containing one or more HTMLEmbedElements or null which represent the
     * &lt;embed&gt; elements in the current document.
     */
-  def plugins: HTMLCollection = js.native
+  def plugins: HTMLCollection[Element] = js.native
 
   /** document.images returns a collection of the images in the current HTML document. */
-  def images: HTMLCollection = js.native
+  def images: HTMLCollection[Element] = js.native
 
   /** Returns the current value of the current range for a formatting command. */
   def queryCommandValue(commandId: String): String = js.native
diff --git a/src/main/scala/org/scalajs/dom/HTMLFormControlsCollection.scala b/src/main/scala/org/scalajs/dom/HTMLFormControlsCollection.scala
@@ -0,0 +1,22 @@
+/** All documentation for facades is thanks to Mozilla Contributors at https://developer.mozilla.org/en-US/docs/Web/API
+  * and available under the Creative Commons Attribution-ShareAlike v2.5 or later.
+  * http://creativecommons.org/licenses/by-sa/2.5/
+  *
+  * Everything else is under the MIT License http://opensource.org/licenses/MIT
+  */
+package org.scalajs.dom
+
+import scala.scalajs.js
+import scala.scalajs.js.annotation._
+import scala.scalajs.js.|
+
+/** The HTMLFormControlsCollection interface represents a collection of HTML form control elements.
+  *
+  * It represents the lists returned by the HTMLFormElement interface's elements property and the HTMLFieldSetElement
+  * interface's elements property.
+  *
+  * This interface replaces one method from HTMLCollection, on which it is based.
+  */
+@js.native
+@JSGlobal
+class HTMLFormControlsCollection private[this] () extends HTMLCollection[RadioNodeList | Element]
diff --git a/src/main/scala/org/scalajs/dom/HTMLFormElement.scala b/src/main/scala/org/scalajs/dom/HTMLFormElement.scala
@@ -33,7 +33,7 @@ abstract class HTMLFormElement extends HTMLElement {
   /** elements returns an HTMLFormControlsCollection (HTML 4 HTMLCollection) of all the form controls contained in the
     * FORM element, with the exception of input elements which have a type attribute of image.
     */
-  def elements: HTMLCollection = js.native
+  def elements: HTMLCollection[Element] = js.native
 
   /** action gets/sets the action of the &lt;form&gt; element. */
   var action: String = js.native
diff --git a/src/main/scala/org/scalajs/dom/HTMLOptionsCollection.scala b/src/main/scala/org/scalajs/dom/HTMLOptionsCollection.scala
@@ -0,0 +1,18 @@
+/** All documentation for facades is thanks to Mozilla Contributors at https://developer.mozilla.org/en-US/docs/Web/API
+  * and available under the Creative Commons Attribution-ShareAlike v2.5 or later.
+  * http://creativecommons.org/licenses/by-sa/2.5/
+  *
+  * Everything else is under the MIT License http://opensource.org/licenses/MIT
+  */
+package org.scalajs.dom
+
+import scala.scalajs.js
+import scala.scalajs.js.annotation._
+
+/** The HTMLOptionsCollection interface represents a collection of <option> HTML elements (in document order) and offers
+  * methods and properties for selecting from the list as well as optionally altering its items. This object is returned
+  * only by the options property of select.
+  */
+@js.native
+@JSGlobal
+class HTMLOptionsCollection private[this] () extends HTMLCollection[HTMLOptionElement]
diff --git a/src/main/scala/org/scalajs/dom/HTMLSelectElement.scala b/src/main/scala/org/scalajs/dom/HTMLSelectElement.scala
@@ -17,7 +17,7 @@ import scala.scalajs.js.annotation._
 abstract class HTMLSelectElement extends HTMLElement {
 
   /** The set of &lt;option&gt; elements contained by this element. Read only. */
-  val options: js.Array[HTMLOptionElement] = js.native
+  val options: HTMLOptionsCollection = js.native
 
   /** The value of this form control, that is, of the first selected option. */
   var value: String = js.native
diff --git a/src/main/scala/org/scalajs/dom/HTMLTableElement.scala b/src/main/scala/org/scalajs/dom/HTMLTableElement.scala
@@ -30,7 +30,7 @@ abstract class HTMLTableElement extends HTMLElement {
     * a &lt;thead&gt; appear first, in tree order, and those members of a &lt;tbody&gt; last, also in tree order. The
     * HTMLCollection is live and is automatically updated when the HTMLTableElement changes.
     */
-  def rows: HTMLCollection = js.native
+  def rows: HTMLCollection[Element] = js.native
 
   /** Is an HTMLTableCaptionElement representing the first &lt;caption&gt; that is a child of the element, or null if
     * none is found. When set, if the object doesn't represent a &lt;caption&gt;, a DOMException with the
@@ -42,7 +42,7 @@ abstract class HTMLTableElement extends HTMLElement {
   /** Returns a live HTMLCollection containing all the &lt;tbody&gt; of the element. The HTMLCollection is live and is
     * automatically updated when the HTMLTableElement changes.
     */
-  def tBodies: HTMLCollection = js.native
+  def tBodies: HTMLCollection[Element] = js.native
 
   /** Is an HTMLTableSectionElement representing the first &lt;thead&gt; that is a child of the element, or null if none
     * is found. When set, if the object doesn't represent a &lt;thead&gt;, a DOMException with the HierarchyRequestError
diff --git a/src/main/scala/org/scalajs/dom/HTMLTableRowElement.scala b/src/main/scala/org/scalajs/dom/HTMLTableRowElement.scala
@@ -24,7 +24,7 @@ abstract class HTMLTableRowElement extends HTMLElement with HTMLTableAlignment {
   /** Returns a live HTMLCollection containing the cells in the row. The HTMLCollection is live and is automatically
     * updated when cells are added or removed.
     */
-  def cells: HTMLCollection = js.native
+  def cells: HTMLCollection[Element] = js.native
 
   var borderColorLight: js.Any = js.native
 
diff --git a/src/main/scala/org/scalajs/dom/HTMLTableSectionElement.scala b/src/main/scala/org/scalajs/dom/HTMLTableSectionElement.scala
@@ -20,7 +20,7 @@ abstract class HTMLTableSectionElement extends HTMLElement with HTMLTableAlignme
   /** Returns a live HTMLCollection containing the rows in the section. The HTMLCollection is live and is automatically
     * updated when rows are added or removed.
     */
-  def rows: HTMLCollection = js.native
+  def rows: HTMLCollection[Element] = js.native
 
   /** Removes the cell at the given position in the section. If the given position is greater (or equal as it starts at
     * zero) than the amount of rows in the section, or is smaller than 0, it raises a DOMException with the
diff --git a/src/main/scala/org/scalajs/dom/NodeList.scala b/src/main/scala/org/scalajs/dom/NodeList.scala
@@ -13,6 +13,6 @@ import scala.scalajs.js.annotation._
   */
 @js.native
 @JSGlobal
-class NodeList[+T <: Node] private[this] () extends DOMList[T] {
+class NodeList[+T <: Node]() extends DOMList[T] {
   def item(index: Int): T = js.native
 }
diff --git a/src/main/scala/org/scalajs/dom/ParentNode.scala b/src/main/scala/org/scalajs/dom/ParentNode.scala
@@ -18,7 +18,7 @@ import scala.scalajs.js.|
 trait ParentNode extends js.Object {
 
   /** Returns a live HTMLCollection containing all objects of type Element that are children of the object. */
-  def children: HTMLCollection = js.native
+  def children: HTMLCollection[Element] = js.native
 
   /** Returns the Element that is the first child of the object, or null if there is none. */
   def firstElementChild: Element = js.native
diff --git a/src/main/scala/org/scalajs/dom/RadioNodeList.scala b/src/main/scala/org/scalajs/dom/RadioNodeList.scala
@@ -0,0 +1,18 @@
+package org.scalajs.dom
+
+import scala.scalajs.js
+import scala.scalajs.js.annotation.JSGlobal
+
+/** The RadioNodeList interface represents a collection of radio elements in a <form> or a <fieldset> element. */
+@js.native
+@JSGlobal
+class RadioNodeList extends NodeList[Node] {
+
+  /** If the underlying element collection contains radio buttons, the value property represents the checked radio
+    * button. On retrieving the value property, the value of the currently checked radio button is returned as a string.
+    * If the collection does not contain any radio buttons or none of the radio buttons in the collection is in checked
+    * state, the empty string is returned. On setting the value property, the first radio button input element whose
+    * value property is equal to the new value will be set to checked.
+    */
+  def value: String = js.native
+}
diff --git a/src/main/scala/org/scalajs/dom/html.scala b/src/main/scala/org/scalajs/dom/html.scala
@@ -10,7 +10,7 @@ object html {
   type Button = HTMLButtonElement
   type BR = HTMLBRElement
   type Canvas = HTMLCanvasElement
-  type Collection = HTMLCollection
+  type Collection[+E] = HTMLCollection[E]
   type DataList = HTMLDataListElement
   type Div = HTMLDivElement
   type DList = HTMLDListElement
diff --git a/src/main/scala/org/scalajs/dom/raw.scala b/src/main/scala/org/scalajs/dom/raw.scala
@@ -320,8 +320,8 @@ object raw {
   @deprecated("use dom.HTMLCanvasElement instead", "2.0.0")
   type HTMLCanvasElement = dom.HTMLCanvasElement
 
-  @deprecated("use dom.HTMLCollectionElement instead", "2.0.0")
-  type HTMLCollectionElement = dom.HTMLCollection
+  @deprecated("use dom.HTMLCollection instead", "2.0.0")
+  type HTMLCollectionElement = dom.HTMLCollection[dom.Element]
 
   @deprecated("use dom.HTMLDataListElement instead", "2.0.0")
   type HTMLDataListElement = dom.HTMLDataListElement

Original file line number	Diff line number	Diff line change
`@@ -17,5 +17,5 @@ import scala.scalajs.js.annotation._`
`17`	`17`	`abstract class HTMLDataListElement extends HTMLElement {`
`18`	`18`
`19`	`19`	`/** A collection of the contained option elements. */`
`20`		`- def options: HTMLCollection = js.native`
	`20`	`+ def options: HTMLCollection[Element] = js.native`
`21`	`21`	`}`