[react-interactions] Add initial docs explaining React Scopes (#16892)
Dominic Gannaway committed
Sep 25, 2019 at 14:57 UTC
d0ebde77f6d1232cefc0da184d731943d78e86f2
2 files changed
+81
-1
packages/react-interactions/accessibility/README.md
new
+78
@@ -0,0 +1,78 @@
1
+# `react-interactions/accessibility`
2
+
3
+*This package is experimental. It is intended for use with the experimental React
4
+Scope API that is not available in open source builds.*
5
+
6
+Scopes allow for querying of the internal React sub-tree to collect handles to
7
+host nodes. Scopes also have their own separate tree structure that allows
8
+traversal of scopes of the same type.
9
+
10
+The core API is documented below. Documentation for individual Accessibility Components
11
+can be found [here](./docs).
12
+
13
+## React Scopes
14
+
15
+Note: React Scopes require the internal React flag `enableScopeAPI`.
16
+
17
+When creating a scope, a query function is required. The query function is used
18
+when collecting host nodes that match the criteria of the query function.
19
+
20
+```jsx
21
+// This query function only matches host nodes that have the type of "div"
22
+const queryFunction = (type: string, props: Object): boolean => {
23
+ if (type === 'div') {
24
+ return true;
25
+ }
26
+ return false;
27
+};
28
+
29
+// Create the scope with the queryFunction above
30
+const DivOnlyScope = React.unstable_createScope(queryFunction);
31
+
32
+// We can now use this in our components. We need to attach
33
+// a ref so we can get the matching host nodes.
34
+function MyComponent(props) {
35
+ const divOnlyScope = useRef(null);
36
+ return (
37
+ <DivOnlyScope ref={divOnlyScope}>
38
+ <div>DIV 1</div>
39
+ <div>DIV 2</div>
40
+ <div>DIV 3</div>
41
+ </DivOnlyScope>
42
+ );
43
+}
44
+
45
+// Using the ref, we can get the host nodes via getScopedNodes()
46
+const divs = divOnlyScope.current.getScopedNodes();
47
+
48
+// [<div>DIV 1</div>, <div>DIV 2</div>, <div>DIV 3</div>]
49
+console.log(divs);
50
+```
51
+
52
+## React Scope Interface
53
+
54
+Scopes require a `ref` to access the internal interface of a particular scope.
55
+The internal interface (`ReactScopeInterface`) exposes the following scope API:
56
+
57
+### getChildren: () => null | Array<ReactScopeInterface>
58
+
59
+Returns an array of all child `ReactScopeInterface` nodes that are
60
+of scopes of the same type. Returns `null` if there are no child scope nodes.
61
+
62
+### getChildrenFromRoot: () => null | Array<ReactScopeInterface>
63
+
64
+Similar to `getChildren`, except this applies the same traversal from the root of the
65
+React internal tree instead of from the scope node position.
66
+
67
+### getParent: () => null | ReactScopeInterface
68
+
69
+Returns the parent `ReactScopeInterface` of the scope node or `null` if none exists.
70
+
71
+### getProps: () => Object
72
+
73
+Returns the current `props` object of the scope node.
74
+
75
+### getScopedNodes: () => null | Array<HTMLElement>
76
+
77
+Returns an array of all child host nodes that successfully match when queried using the
78
+query function passed to the scope. Returns `null` if there are no matching host nodes.
\ No newline at end of file
packages/react-interactions/events/README.md
+3
-1
@@ -1,4 +1,4 @@
1
-# `react-ui/events`
1
+# `react-interactions/events`
2
3
*This package is experimental. It is intended for use with the experimental React
4
events API that is not available in open source builds.*
@@ -12,6 +12,8 @@ can be found [here](./docs).
12
13
## Event Responder Interface
14
15
+Note: React Responders require the internal React flag `enableFlareAPI`.
16
+
17
An Event Responder Interface is defined using an object. Each responder can define DOM
18
events to listen to, handle the synthetic responder events, dispatch custom
19
events, and implement a state machine.