From 1f5f21956fe3f94029ed94d63cea3f0a8a9c7fc4 Mon Sep 17 00:00:00 2001
From: Dominic Gannaway <dg@domgan.com>
Date: Wed, 25 Sep 2019 13:49:38 +0100
Subject: [PATCH] [react-interactions] Add initial docs explaining React Scopes

---
 .../accessibility/README.md                   | 78 +++++++++++++++++++
 packages/react-interactions/events/README.md  |  4 +-
 2 files changed, 81 insertions(+), 1 deletion(-)
 create mode 100644 packages/react-interactions/accessibility/README.md

diff --git a/packages/react-interactions/accessibility/README.md b/packages/react-interactions/accessibility/README.md
new file mode 100644
index 0000000000000..9e910b18778f3
--- /dev/null
+++ b/packages/react-interactions/accessibility/README.md
@@ -0,0 +1,78 @@
+# `react-interactions/accessibility`
+
+*This package is experimental. It is intended for use with the experimental React
+Scope API that is not available in open source builds.*
+
+Scopes allow for querying of the internal React sub-tree to collect handles to
+host nodes. Scopes also have their own separate tree structure that allows
+traversal of scopes of the same type.
+
+The core API is documented below. Documentation for individual Accessibility Components
+can be found [here](./docs).
+
+## React Scopes
+
+Note: React Scopes require the internal React flag `enableScopeAPI`.
+
+When creating a scope, a query function is required. The query function is used
+when collecting host nodes that match the criteria of the query function.
+
+```jsx
+// This query function only matches host nodes that have the type of "div"
+const queryFunction = (type: string, props: Object): boolean => {
+  if (type === 'div') {
+    return true;
+  }
+  return false;
+};
+
+// Create the scope with the queryFunction above
+const DivOnlyScope = React.unstable_createScope(queryFunction);
+
+// We can now use this in our components. We need to attach
+// a ref so we can get the matching host nodes.
+function MyComponent(props) {
+  const divOnlyScope = useRef(null);
+  return (
+    <DivOnlyScope ref={divOnlyScope}>
+      <div>DIV 1</div>
+      <div>DIV 2</div>
+      <div>DIV 3</div>
+    </DivOnlyScope>
+  );
+}
+
+// Using the ref, we can get the host nodes via getScopedNodes()
+const divs = divOnlyScope.current.getScopedNodes();
+
+// [<div>DIV 1</div>, <div>DIV 2</div>, <div>DIV 3</div>]
+console.log(divs);
+```
+
+## React Scope Interface
+
+Scopes require a `ref` to access the internal interface of a particular scope.
+The internal interface (`ReactScopeInterface`) exposes the following scope API:
+
+### getChildren: () => null | Array<ReactScopeInterface>
+
+Returns an array of all child `ReactScopeInterface` nodes that are
+of scopes of the same type. Returns `null` if there are no child scope nodes.
+
+### getChildrenFromRoot: () => null | Array<ReactScopeInterface>
+
+Similar to `getChildren`, except this applies the same traversal from the root of the
+React internal tree instead of from the scope node position.
+
+### getParent: () => null | ReactScopeInterface
+
+Returns the parent `ReactScopeInterface` of the scope node or `null` if none exists.
+
+### getProps: () => Object
+
+Returns the current `props` object of the scope node.
+
+### getScopedNodes: () => null | Array<HTMLElement>
+
+Returns an array of all child host nodes that successfully match when queried using the
+query function passed to the scope. Returns `null` if there are no matching host nodes.
\ No newline at end of file
diff --git a/packages/react-interactions/events/README.md b/packages/react-interactions/events/README.md
index e40aca7cc1cfb..a8e093e7cd6ad 100644
--- a/packages/react-interactions/events/README.md
+++ b/packages/react-interactions/events/README.md
@@ -1,4 +1,4 @@
-# `react-ui/events`
+# `react-interactions/events`
 
 *This package is experimental. It is intended for use with the experimental React
 events API that is not available in open source builds.*
@@ -12,6 +12,8 @@ can be found [here](./docs).
 
 ## Event Responder Interface
 
+Note: React Responders require the internal React flag `enableFlareAPI`.
+
 An Event Responder Interface is defined using an object. Each responder can define DOM
 events to listen to, handle the synthetic responder events, dispatch custom
 events, and implement a state machine.