docs: move toHaveSelection from the deprecated section (#717)

Author: silviuaavram

README.md

@@ -81,6 +81,7 @@ clear to read and to maintain.
   - [`toBePartiallyChecked`](#tobepartiallychecked)
   - [`toHaveRole`](#tohaverole)
   - [`toHaveErrorMessage`](#tohaveerrormessage)
+  - [`toHaveSelection`](#tohaveselection)
   - [`toBePressed`](#tobepressed)
   - [`toBePartiallyPressed`](#tobepartiallypressed)
   - [`toAppearBefore`](#toappearbefore)
@@ -89,7 +90,6 @@ clear to read and to maintain.
   - [`toBeEmpty`](#tobeempty)
   - [`toBeInTheDOM`](#tobeinthedom)
   - [`toHaveDescription`](#tohavedescription)
-  - [`toHaveSelection`](#tohaveselection)
 - [Inspiration](#inspiration)
 - [Other Solutions](#other-solutions)
 - [Guiding Principles](#guiding-principles)
@@ -1312,6 +1312,73 @@ expect(timeInput).not.toHaveErrorMessage('Pikachu!')
 
 <hr />
 
+### `toHaveSelection`
+
+This allows to assert that an element has a
+[text selection](https://developer.mozilla.org/en-US/docs/Web/API/Selection).
+
+This is useful to check if text or part of the text is selected within an
+element. The element can be either an input of type text, a textarea, or any
+other element that contains text, such as a paragraph, span, div etc.
+
+NOTE: the expected selection is a string, it does not allow to check for
+selection range indices.
+
+```typescript
+toHaveSelection(expectedSelection?: string)
+```
+
+#### Examples
+
+```html
+<div>
+  <input type="text" value="text selected text" data-testid="text" />
+  <textarea data-testid="textarea">text selected text</textarea>
+  <p data-testid="prev">prev</p>
+  <p data-testid="parent">
+    text <span data-testid="child">selected</span> text
+  </p>
+  <p data-testid="next">next</p>
+</div>
+```
+
+```javascript
+getByTestId('text').setSelectionRange(5, 13)
+expect(getByTestId('text')).toHaveSelection('selected')
+
+getByTestId('textarea').setSelectionRange(0, 5)
+expect(getByTestId('textarea')).toHaveSelection('text ')
+
+const selection = document.getSelection()
+const range = document.createRange()
+selection.removeAllRanges()
+selection.empty()
+selection.addRange(range)
+
+// selection of child applies to the parent as well
+range.selectNodeContents(getByTestId('child'))
+expect(getByTestId('child')).toHaveSelection('selected')
+expect(getByTestId('parent')).toHaveSelection('selected')
+
+// selection that applies from prev all, parent text before child, and part child.
+range.setStart(getByTestId('prev'), 0)
+range.setEnd(getByTestId('child').childNodes[0], 3)
+expect(queryByTestId('prev')).toHaveSelection('prev')
+expect(queryByTestId('child')).toHaveSelection('sel')
+expect(queryByTestId('parent')).toHaveSelection('text sel')
+expect(queryByTestId('next')).not.toHaveSelection()
+
+// selection that applies from part child, parent text after child and part next.
+range.setStart(getByTestId('child').childNodes[0], 3)
+range.setEnd(getByTestId('next').childNodes[0], 2)
+expect(queryByTestId('child')).toHaveSelection('ected')
+expect(queryByTestId('parent')).toHaveSelection('ected text')
+expect(queryByTestId('prev')).not.toHaveSelection()
+expect(queryByTestId('next')).toHaveSelection('ne')
+```
+
+<hr />
+
 ### `toBePressed`
 
 This allows to check whether given element is
@@ -1570,71 +1637,6 @@ expect(deleteButton).not.toHaveDescription()
 expect(deleteButton).toHaveDescription('') // Missing or empty description always becomes a blank string
 ```
 
-<hr />
-
-### `toHaveSelection`
-
-This allows to assert that an element has a
-[text selection](https://developer.mozilla.org/en-US/docs/Web/API/Selection).
-
-This is useful to check if text or part of the text is selected within an
-element. The element can be either an input of type text, a textarea, or any
-other element that contains text, such as a paragraph, span, div etc.
-
-NOTE: the expected selection is a string, it does not allow to check for
-selection range indeces.
-
-```typescript
-toHaveSelection(expectedSelection?: string)
-```
-
-```html
-<div>
-  <input type="text" value="text selected text" data-testid="text" />
-  <textarea data-testid="textarea">text selected text</textarea>
-  <p data-testid="prev">prev</p>
-  <p data-testid="parent">
-    text <span data-testid="child">selected</span> text
-  </p>
-  <p data-testid="next">next</p>
-</div>
-```
-
-```javascript
-getByTestId('text').setSelectionRange(5, 13)
-expect(getByTestId('text')).toHaveSelection('selected')
-
-getByTestId('textarea').setSelectionRange(0, 5)
-expect('textarea').toHaveSelection('text ')
-
-const selection = document.getSelection()
-const range = document.createRange()
-selection.removeAllRanges()
-selection.empty()
-selection.addRange(range)
-
-// selection of child applies to the parent as well
-range.selectNodeContents(getByTestId('child'))
-expect(getByTestId('child')).toHaveSelection('selected')
-expect(getByTestId('parent')).toHaveSelection('selected')
-
-// selection that applies from prev all, parent text before child, and part child.
-range.setStart(getByTestId('prev'), 0)
-range.setEnd(getByTestId('child').childNodes[0], 3)
-expect(queryByTestId('prev')).toHaveSelection('prev')
-expect(queryByTestId('child')).toHaveSelection('sel')
-expect(queryByTestId('parent')).toHaveSelection('text sel')
-expect(queryByTestId('next')).not.toHaveSelection()
-
-// selection that applies from part child, parent text after child and part next.
-range.setStart(getByTestId('child').childNodes[0], 3)
-range.setEnd(getByTestId('next').childNodes[0], 2)
-expect(queryByTestId('child')).toHaveSelection('ected')
-expect(queryByTestId('parent')).toHaveSelection('ected text')
-expect(queryByTestId('prev')).not.toHaveSelection()
-expect(queryByTestId('next')).toHaveSelection('ne')
-```
-
 ## Inspiration
 
 This whole library was extracted out of Kent C. Dodds' [DOM Testing