docs: add queries pages

book/src/SUMMARY.md

@@ -6,29 +6,29 @@
         - [About Queries](./core/queries/about-queries.md)
         - [By Role](./core/queries/by-role.md)
         - [By Label Text](./core/queries/by-label-text.md)
-        - [By Placeholder Text]()
-        - [By Text]()
-        - [By Display Value]()
-        - [By Alt Text]()
-        - [By Title]()
-        - [By Test ID]()
+        - [By Placeholder Text](./core/queries/by-placeholder-text.md)
+        - [By Text](./core/queries/by-text.md)
+        - [By Display Value](./core/queries/by-display-value.md)
+        - [By Alt Text](./core/queries/by-alt-text.md)
+        - [By Title](./core/queries/by-title.md)
+        - [By Test ID](./core/queries/by-test-id.md)
     - [User Actions](./core/user-actions/README.md)
         - [Firing Events](./core/user-actions/firing-events.md)
         - [Async Methods]()
         - [Appearance and Disappearance]()
         - [Considerations]()
     - [Advanced](./core/advanced/README.md)
-        - [Accessibility]()
+        - [Accessibility](./core/advanced/accessibility.md)
         - [Custom Queries]()
         - [Debugging]()
         - [Querying Within Elements]()
-        - [Configuration Options]()
+        - [Configuration Options](./core/advanced/configuration-options.md)
 - [Frameworks](./frameworks/README.md)
-    - [DOM Testing Library](./frameworks/dom.md)
+    - [DOM Testing Library](./frameworks/dom/README.md)
         - [Introduction]()
-        - [Install]()
+        - [Install](./frameworks/dom/install.md)
         - [Example]()
         - [Setup]()
-        - [API]()
+        - [API](./frameworks/dom/api.md)
         - [Cheatsheet]()
 - [Contributing]()

book/src/core/advanced/README.md

@@ -1,3 +1,7 @@
 # Advanced
 
-TODO
+- [Accessibility](./accessibility.md)
+- Custom Queries
+- Debugging
+- Querying Within Elements
+- [Configuration Options](./configuration-options.md)

book/src/core/advanced/accessibility.md

@@ -0,0 +1,109 @@
+# Accessibility
+
+## Testing for Accessibility
+
+One of the guiding principles of the Testing Library APIs is that they should enable you to test your app the way your users use it, including through accessibility interfaces like screen readers.
+
+See the page on [queries](../queries/about-queries.md#priority) for details on how using a semantic HTML query can make sure your app works with browser accessibility APIs.
+
+## `get_roles`
+
+```rust,ignore
+use testing_library_dom::{get_roles, GetRolesOptions};
+use wasm_bindgen_test::console_log;
+use web_sys::window;
+
+let document = window()
+    .expect("Window should exist.")
+    .document()
+    .expect("Document should exist.");
+
+let nav = document.create_element("nav")?;
+nav.set_inner_html("\
+<ul>\
+    <li>Item 1</li>\
+    <li>Item 2</li>\
+</ul>\
+");
+
+console_log!("{:#?}", get_roles(nav, GetRolesOptions::default()));
+
+// {
+//     Navigation: [
+//         Element {
+//             obj: Node {
+//                 obj: EventTarget {
+//                     obj: Object {
+//                         obj: JsValue(HTMLElement),
+//                     },
+//                 },
+//             },
+//         },
+//     ],
+//     List: [
+//         Element {
+//             obj: Node {
+//                 obj: EventTarget {
+//                     obj: Object {
+//                         obj: JsValue(HTMLUListElement),
+//                     },
+//                 },
+//             },
+//         },
+//     ],
+//     Listitem: [
+//         Element {
+//             obj: Node {
+//                 obj: EventTarget {
+//                     obj: Object {
+//                         obj: JsValue(HTMLLIElement),
+//                     },
+//                 },
+//             },
+//         },
+//         Element {
+//             obj: Node {
+//                 obj: EventTarget {
+//                     obj: Object {
+//                         obj: JsValue(HTMLLIElement),
+//                     },
+//                 },
+//             },
+//         },
+//     ],
+// }
+```
+
+## `is_inaccessible`
+
+This function will compute if the given element should be excluded from the accessibility API by the browser. It implements every **MUST** criteria from the [Excluding Elements from the Accessibility Tree](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion) section in WAI-ARIA 1.2 with the exception of checking the `role` attribute.
+
+It is defined as:
+
+```rust,ignore
+fn is_inaccessible(element: &Element) -> bool;
+```
+
+## `log_roles`
+
+This helper function can be used to print out a list of all the implicit ARIA roles within a tree of DOM nodes, each role containing a list of all of the nodes which match that role. This can be helpful for finding ways to query the DOM under test with [By Role](../queries/by-role.md).
+
+```rust,ignore
+use testing_library_dom::{log_roles, PrettyRolesOptions};
+use web_sys::window;
+
+let document = window()
+    .expect("Window should exist.")
+    .document()
+    .expect("Document should exist.");
+
+let nav = document.create_element("nav")?;
+nav.set_inner_html("\
+<ul>\
+    <li>Item 1</li>\
+    <li>Item 2</li>\
+</ul>\
+");
+
+log_roles(nav, PrettyRolesOptions::default());
+```

book/src/core/advanced/configuration-options.md

@@ -0,0 +1,60 @@
+# Configuration Options
+
+## Introduction
+
+## Options
+
+### `default_hidden`
+
+The default value for the [`hidden` option](../queries/by-role.md#hidden) used by `get_by_role`. Defaults to `false`.
+
+### `default_ignore`
+
+The default value for the [`ignore` option](../queries/by-text.md#ignore) used by `get_by_text`. Also determines the nodes that are being ignored when errors are printed.
+
+Defaults to `script, style`.
+
+### `throw_suggestions` (experimental)
+
+When enabled, if [better queries](../queries/about-queries.md#priority) are available, the test will fail and provide a suggested query to use instead. Defaults to `false`.
+
+To disable a suggestion for a single query just add `.suggest(false)` as an option.
+
+```rust,ignore
+// Will not throw a suggestion.
+screen.get_by_test_id("foo", MatcherOptions::default().suggest(false))
+```
+
+> **Note**
+>
+> When this option is enabled, it may provide suggestions that lack an intuitive implementation. Typically this happens for [roles which cannot be named](https://w3c.github.io/aria/#namefromprohibited), most notably paragraphs. For instance, if you attempt to use `get_by_text`, you may encounter the following error:
+>
+> ```text
+> A better query is available, try this:
+>     get_by_role(AriaRole::Paragraph)
+> ```
+>
+> However, there is no direct way to query paragraphs using the config parameter, such as in `get_by_role(AriaRole::Paragraph, ByRoleOptions::default().name("Hello World"))`.
+>
+> To address this issue, you can leverage a custom function to validate the element's structure, as shown in the example below. More information can be found in the [GitHub issue](https://github.com/testing-library/dom-testing-library/issues/1306).
+>
+> ```rust,ignore
+> get_by_role(
+>     AriaRole::Paragraph,
+>     ByRoleOptions::default().name(Rc::new(|_, element| {
+>         element.map(|element| element.text_content()).is_some_and(|content| content == "Hello World")
+>     }))
+> )
+> ```
+
+### `test_id_attribute`
+
+The attribute used by `get_by_test_id` and related queries. Defaults to `data-testid`.
+
+### `get_element_error`
+
+A function that returns the error used when [get or find queries](../queries/about-queries.md#types-of-queries) fail. Takes the error message and container as arguments.
+
+### `async_util_timeout`
+
+The global timeout value in milliseconds used by `wait_for` utilities. Defaults to 1000ms.

book/src/core/queries/README.md

@@ -2,10 +2,10 @@
 
 - [About Queries](./about-queries.md)
 - [By Role](./by-role.md)
-      <!-- -   [By Label Text]()
-- [By Placeholder Text]()
-- [By Text]()
-- [By Display Value]()
-- [By Alt Text]()
-- [By Title]()
-- [By Test ID]() -->
+- [By Label Text](./by-label-text.md)
+- [By Placeholder Text](./by-placeholder-text.md)
+- [By Text](./by-label-text.md)
+- [By Display Value](./by-display-value.md)
+- [By Alt Text](./by-alt-text.md)
+- [By Title](./by-title.md)
+- [By Test ID](./by-test-id.md)