Revise in preparation for 3.0.0 release

Author: bcarroll22

docs/api-async.md

@@ -1,7 +1,7 @@
 ---
 id: api-async
-title: Async
-sidebar_label: Async
+title: Async Utilities
+sidebar_label: Async Utilities
 ---
 
 Several utilities are provided for dealing with asynchronous code. These can be useful to wait for
@@ -26,8 +26,8 @@ expectations to pass. The `wait` function is a small wrapper around the
 example:
 
 ```javascript
-await wait(() => getByLabelText(container, 'username'));
-getByLabelText(container, 'username').value = 'chucknorris';
+await wait(() => getByLabelText('username'));
+getByLabelText('username').value = 'chucknorris';
 ```
 
 This can be useful if you have a unit test that mocks API calls and you need to wait for your mock
@@ -49,38 +49,70 @@ the event loop (in a `setTimeout`) before starting the intervals.
 function waitForElement<T>(
   callback: () => T,
   options?: {
-    container?: ReactTestInstance;
     timeout?: number;
     interval?: number;
   },
 ): Promise<T>;
 ```
 
-When in need to wait for DOM elements to appear, disappear, or change you can use `waitForElement`.
-The `waitForElement` function is a similar to `wait`, but is a helper specifically intended to wait
-for an element.
+When you need to wait for elements to appear, you can use `waitForElement`. The `waitForElement`
+function is a similar to `wait`, but is specifically intended to wait for an element to appear.
+Additionally, the result is returned for you to use.
 
 Here's a simple example:
 
 ```javascript
-const usernameElement = await waitForElement(() => getByA11yLabel(container, 'username'), {
-  container,
-});
-expect(usernameElement.props.children).toBe('chucknorris');
+const usernameElement = await waitForElement(() => getByA11yLabel('username'));
+expect(usernameElement).toHaveTextContent('chucknorris');
 ```
 
 You can also wait for multiple elements at once:
 
 ```javascript
-const [usernameElement, passwordElement] = await waitForElement(
-  () => [getByA11yLabel(container, 'username'), getByA11yLabel(container, 'password')],
-  { container },
-);
+const [usernameElement, passwordElement] = await waitForElement(() => [
+  getByA11yLabel('username'),
+  getByA11yLabel('password'),
+]);
 ```
 
-The default `container` is the root `ReactTestInstance` that is the result of `render`. Make sure
-the elements you wait for will be attached to it, or set a different `ReactTestInstance` as a
-container.
+The default `timeout` is `4500ms` which will keep you under
+[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).
+
+The default `interval` is `50ms`. However it will run your callback immediately on the next tick of
+the event loop (in a `setTimeout`) before starting the intervals.
+
+## `waitForElementToBeRemoved`
+
+```typescript
+function waitForElementToBeRemoved<T>(
+  callback: () => T,
+  options?: {
+    timeout?: number;
+    interval?: number;
+  },
+): Promise<T>;
+```
+
+When you need to wait for elements to be removed, or you can use `waitForElementToBeRemoved`. The
+`waitForElementToBeRemoved` function is a similar to `wait`, but is a helper specifically intended
+to wait for an element to be removed from the tree. Similarly to `waitForElement` the result of the
+callback is returned as a Promise, but in most cases you won't need it.
+
+Here's a simple example:
+
+```javascript
+const listItems = await waitForElementToBeRemoved(() => queryAllByA11yLabel('list-item'));
+expect(listItems).toHaveLength(0);
+```
+
+You can also wait for multiple elements to be removed at once:
+
+```javascript
+const [usernameElement, passwordElement] = await waitForElementToBeRemoved(() => [
+  queryByA11yLabel('username'),
+  queryByA11yLabel('password'),
+]);
+```
 
 The default `timeout` is `4500ms` which will keep you under
 [Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).

docs/api-events.md

@@ -20,8 +20,8 @@ fireEvent[eventName](node: FiberRoot, eventProperties: NativeEvent)
 ```
 
 Convenience methods for firing events. Check out
-[src/events.js](https://github.com/testing-library/native-testing-library/blob/master/src/events.js) for
-a full list as well as `validTargets` for every event type.
+[src/events.js](https://github.com/testing-library/native-testing-library/blob/master/src/events.js)
+for a full list as well as `validTargets` for every event type.
 
 ```javascript
 import { fireEvent, render } from 'native-testing-library';

docs/api-helpers.md

@@ -6,13 +6,13 @@ sidebar_label: Helpers
 
 ## Custom Queries
 
-`native-testing-library` exposes many of the helper functions that are used to implement the default
+`native-testing-library` exposes some of the helper functions that are used to implement the default
 queries. You can use the helpers to build custom queries. For example, the code below shows a way to
 query your TestInstance by a `style` prop. Note: test files would need to now import `test-utils.js`
 instead of using `native-testing-library` directly. Also note, please never actually implement this
 helper, it's just an example of what's possible.
 
-```js
+```javascript
 // test-utils.js
 import * as nativeTestingLib from 'native-testing-library';
 
@@ -54,10 +54,10 @@ export {
 getNodeText(node: React.ReactElement<any>)
 ```
 
-Returns the complete text content of a html element, removing any extra whitespace, and joining
-children that are an array. The intention is to treat text in nodes exactly as how it is perceived
-by users in a browser, where any extra whitespace within words in the html code is not meaningful
-when the text is rendered, and all text appears as one cohesive string regardless of the code.
+Returns the complete text content of an element, removing any extra whitespace, and joining children
+that are an array. The intention is to treat text in nodes exactly as how it is perceived by users
+in a browser, where any extra whitespace within words in the html code is not meaningful when the
+text is rendered, and all text appears as one cohesive string regardless of the code.
 
 ```javascript
 const inputNode = <TextInput value="words" />;
@@ -85,30 +85,30 @@ const inputNode = <TextInput value="words" />;
 getNodeText(inputNode); // "words"
 ```
 
-## `getQueriesForElement` APIs
+## `within` and ``getQueriesForElement` APIs
 
-`getQueriesForElement` takes a FiberRoot and binds it to the raw query functions, allowing them to
-be used without specifying a container.
+`within` (an alias to `getQueriesForElement`) takes a `ReactTestRendererInstance` and binds it to
+the raw query functions, allowing them to be used without manually specifying a container.
 
 Example: To get the username input of a login form within a `<LoginModal />`, you could do:
 
 ```js
-import { render, getQueriesForElement } from 'react-testing-library';
+import { render, within } from 'native-testing-library';
 
 const { getByA11yLabel } = render(<LoginModal />);
 const loginForm = getByA11yLabel('login-form');
 
-getQueriesForElement(loginForm).getByPlaceholder('Username');
+within(loginForm).getByPlaceholder('Username');
 ```
 
 ## Debugging
 
-When you use any `get` calls in your test cases, the current state of the `container` (React tree)
-gets printed on the console. For example:
+When you use any `get` calls in your test cases, the current contents of the `baseElement` get
+printed on the console. For example:
 
 ```javascript
 // <Text>Hello world</Text>
-getByText(container, 'Goodbye world'); // will fail by throwing error
+getByText('Goodbye world'); // will fail by throwing error
 ```
 
 The above test case will fail, however it prints the state of your React tree being tested, so you

docs/api-queries.md

@@ -4,6 +4,29 @@ title: Queries
 sidebar_label: Queries
 ---
 
+## Using queries
+
+All queries are exported directly from the entry point, but you likely won't need to use them that
+way in most cases. For instance, you can do the following:
+
+```javascript
+import { getByText } from 'native-testing-library';
+
+getByText(container, 'hello world');
+```
+
+but you likely won't need to. Most queries you will run are on the result of render. You can use
+those in this way:
+
+```javascript
+const { getByText } = render(<Text>hello world</Text>);
+
+getByText('hello world');
+```
+
+This page is written in the format of the first example because it is documentation for the query
+API, not documentation for the render result.
+
 ## Variants
 
 > `getBy` queries are shown by default in the [query documentation](#queries) below.
@@ -62,7 +85,7 @@ See [TextMatch](#textmatch) for documentation on what can be passed to a query.
 
 ```typescript
 getByA11yHint(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -91,7 +114,7 @@ getByA11yHint('summary'); // returns the View node
 
 ```typescript
 getByA11yLabel(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -131,7 +154,7 @@ getByA11yLabel('username'); // returns the TextInput node
 
 ```typescript
 getByA11yRole(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -160,7 +183,7 @@ getByA11yRole('summary'); // returns the View node
 
 ```typescript
 getByA11yStates(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: Array<string>
 ): FiberRoot
 ```
@@ -183,7 +206,7 @@ getByA11yStates(['disabled']); // returns the View node
 
 ```typescript
 getByA11yTraits(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: Array<string>,
 ): FiberRoot
 ```
@@ -206,7 +229,7 @@ getByA11yTraits(['button']); // returns the View node
 
 ```typescript
 getByPlaceholder(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -234,10 +257,9 @@ getByPlaceholder('Username'); // returns the TextInput node
 
 ```typescript
 getByText(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: TextMatch,
   options?: {
-    types?: array = ['Text', 'TextInput'],
     trim?: boolean = true,
     collapseWhitespace?: boolean = true,
     exact?: boolean = true,
@@ -256,13 +278,40 @@ const { getByText } = render(<Text>About ℹ</Text>);
 getByText(/about/i); // returns the Text node
 ```
 
+### `ByTitle`
+
+> getByTitle, queryByTitle, getAllByTitle, queryAllByTitle, findByTitle, findAllByTitle
+
+```typescript
+getByTitle(
+  container: ReactTestRendererInstance,
+  match: TextMatch,
+  options?: {
+    trim?: boolean = true,
+    collapseWhitespace?: boolean = true,
+    exact?: boolean = true,
+    normalizer?: NormalizerFn,
+  }): FiberRoot
+```
+
+This will search for all elements with `props.title` matching the given by their value
+[`TextMatch`](#textmatch).
+
+```js
+import { render } from 'native-testing-library';
+
+const { getByTitle } = render(<Button title="About" />);
+
+getByTitle(/about/i); // returns the Button node
+```
+
 ### `ByValue`
 
 > getByValue, queryByValue, getAllByValue, queryAllByValue, findByValue, findAllByValue
 
 ```typescript
 getByValue(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -290,7 +339,7 @@ getByValue(/about/i); // returns the Input node
 
 ```typescript
 getByTestId(
-  container: ReactTestInstance,
+  container: ReactTestRendererInstance,
   match: TextMatch,
   options?: {
     trim?: boolean = true,