Skip to content

Commit b6173e6

Browse files
authored
[react-interactions] Add DO_NOT_USE to Scope methods (#17835)
1 parent 8aefb19 commit b6173e6

File tree

11 files changed

+170
-157
lines changed

11 files changed

+170
-157
lines changed

packages/react-interactions/accessibility/README.md

Lines changed: 0 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -14,74 +14,11 @@ can be found [here](./docs).
1414

1515
Note: React Scopes require the internal React flag `enableScopeAPI`.
1616

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 getAllNodes()
46-
const divs = divOnlyScope.current.getAllNodes();
47-
48-
// [<div>DIV 1</div>, <div>DIV 2</div>, <div>DIV 3</div>]
49-
console.log(divs);
50-
```
51-
5217
## React Scope Interface
5318

5419
Scopes require a `ref` to access the internal interface of a particular scope.
5520
The internal interface (`ReactScopeInterface`) exposes the following scope API:
5621

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-
### getAllNodes: () => 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.
79-
80-
### getFirstNode: () => null | HTMLElement
81-
82-
Returns the first child host node that successfully matches when queried using the
83-
query function passed to the scope. Returns `null` if there is no matching host node.
84-
8522
### containsNode: (node: HTMLElement) => boolean
8623

8724
Returns `true` or `false` depending on if the given `HTMLElement` is a descendant

packages/react-interactions/accessibility/docs/TabbableScopeQuery.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ function FocusableNodeCollector(props) {
1515
const scope = scopeRef.current;
1616

1717
if (scope) {
18-
const tabFocusableNodes = scope.queryAllNodes(tabbableScopeQuery);
18+
const tabFocusableNodes = scope.DO_NOT_USE_queryAllNodes(tabbableScopeQuery);
1919
if (tabFocusableNodes && props.onFocusableNodes) {
2020
props.onFocusableNodes(tabFocusableNodes);
2121
}

packages/react-interactions/accessibility/src/FocusContain.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ export default function FocusContain({
7171
disabled !== true &&
7272
!scope.containsNode(document.activeElement)
7373
) {
74-
const fistElem = scope.queryFirstNode(scopeQuery);
74+
const fistElem = scope.DO_NOT_USE_queryFirstNode(scopeQuery);
7575
if (fistElem !== null) {
7676
fistElem.focus();
7777
}

packages/react-interactions/accessibility/src/FocusGroup.js

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ function focusGroupItem(
3535
cell: ReactScopeMethods,
3636
event: KeyboardEvent,
3737
): void {
38-
const firstScopedNode = cell.queryFirstNode(scopeQuery);
38+
const firstScopedNode = cell.DO_NOT_USE_queryFirstNode(scopeQuery);
3939
if (firstScopedNode !== null) {
4040
firstScopedNode.focus();
4141
event.preventDefault();
@@ -46,7 +46,7 @@ function getPreviousGroupItem(
4646
group: ReactScopeMethods,
4747
currentItem: ReactScopeMethods,
4848
): null | ReactScopeMethods {
49-
const items = group.getChildren();
49+
const items = group.DO_NOT_USE_getChildren();
5050
if (items !== null) {
5151
const currentItemIndex = items.indexOf(currentItem);
5252
const wrap = getGroupProps(currentItem).wrap;
@@ -63,7 +63,7 @@ function getNextGroupItem(
6363
group: ReactScopeMethods,
6464
currentItem: ReactScopeMethods,
6565
): null | ReactScopeMethods {
66-
const items = group.getChildren();
66+
const items = group.DO_NOT_USE_getChildren();
6767
if (items !== null) {
6868
const currentItemIndex = items.indexOf(currentItem);
6969
const wrap = getGroupProps(currentItem).wrap;
@@ -78,9 +78,9 @@ function getNextGroupItem(
7878
}
7979

8080
function getGroupProps(currentCell: ReactScopeMethods): Object {
81-
const group = currentCell.getParent();
81+
const group = currentCell.DO_NOT_USE_getParent();
8282
if (group !== null) {
83-
const groupProps = group.getProps();
83+
const groupProps = group.DO_NOT_USE_getProps();
8484
if (groupProps && groupProps.type === 'group') {
8585
return groupProps;
8686
}
@@ -125,19 +125,21 @@ export function createFocusGroup(
125125
onKeyDown(event: KeyboardEvent): void {
126126
const currentItem = scopeRef.current;
127127
if (currentItem !== null) {
128-
const group = currentItem.getParent();
129-
const groupProps = group && group.getProps();
128+
const group = currentItem.DO_NOT_USE_getParent();
129+
const groupProps = group && group.DO_NOT_USE_getProps();
130130
if (group !== null && groupProps.type === 'group') {
131131
const portrait = groupProps.portrait;
132132
const key = event.key;
133133

134134
if (key === 'Tab') {
135135
const tabScopeQuery = getGroupProps(currentItem).tabScopeQuery;
136136
if (tabScopeQuery) {
137-
const groupScope = currentItem.getParent();
137+
const groupScope = currentItem.DO_NOT_USE_getParent();
138138
if (groupScope) {
139139
const activeNode = document.activeElement;
140-
const nodes = groupScope.queryAllNodes(tabScopeQuery);
140+
const nodes = groupScope.DO_NOT_USE_queryAllNodes(
141+
tabScopeQuery,
142+
);
141143
for (let i = 0; i < nodes.length; i++) {
142144
const node = nodes[i];
143145
if (node !== activeNode) {

packages/react-interactions/accessibility/src/FocusManager.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ export function focusFirst(
1616
scopeQuery: (type: string | Object, props: Object) => boolean,
1717
scope: ReactScopeMethods,
1818
): void {
19-
const firstNode = scope.queryFirstNode(scopeQuery);
19+
const firstNode = scope.DO_NOT_USE_queryFirstNode(scopeQuery);
2020
if (firstNode) {
2121
focusElem(firstNode);
2222
}
@@ -101,7 +101,7 @@ export function focusPrevious(
101101
export function getNextScope(
102102
scope: ReactScopeMethods,
103103
): null | ReactScopeMethods {
104-
const allScopes = scope.getChildrenFromRoot();
104+
const allScopes = scope.DO_NOT_USE_getChildrenFromRoot();
105105
if (allScopes === null) {
106106
return null;
107107
}
@@ -115,7 +115,7 @@ export function getNextScope(
115115
export function getPreviousScope(
116116
scope: ReactScopeMethods,
117117
): null | ReactScopeMethods {
118-
const allScopes = scope.getChildrenFromRoot();
118+
const allScopes = scope.DO_NOT_USE_getChildrenFromRoot();
119119
if (allScopes === null) {
120120
return null;
121121
}

packages/react-interactions/accessibility/src/FocusTable.js

Lines changed: 25 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ function focusScope(
4242
cell: ReactScopeMethods,
4343
event?: KeyboardEvent,
4444
): void {
45-
const firstScopedNode = cell.queryFirstNode(scopeQuery);
45+
const firstScopedNode = cell.DO_NOT_USE_queryFirstNode(scopeQuery);
4646
if (firstScopedNode !== null) {
4747
firstScopedNode.focus();
4848
if (event) {
@@ -58,13 +58,13 @@ function focusCellByColumnIndex(
5858
columnIndex: number,
5959
event?: KeyboardEvent,
6060
): void {
61-
const cells = row.getChildren();
61+
const cells = row.DO_NOT_USE_getChildren();
6262
if (cells !== null) {
6363
let colSize = 0;
6464
for (let i = 0; i < cells.length; i++) {
6565
const cell = cells[i];
6666
if (cell) {
67-
colSize += cell.getProps().colSpan || 1;
67+
colSize += cell.DO_NOT_USE_getProps().colSpan || 1;
6868
if (colSize > columnIndex) {
6969
focusScope(scopeQuery, cell, event);
7070
return;
@@ -84,7 +84,7 @@ function getCellIndexes(
8484
if (cell === currentCell) {
8585
return [i, i + totalColSpan];
8686
}
87-
const colSpan = cell.getProps().colSpan;
87+
const colSpan = cell.DO_NOT_USE_getProps().colSpan;
8888
if (colSpan) {
8989
totalColSpan += colSpan - 1;
9090
}
@@ -93,9 +93,9 @@ function getCellIndexes(
9393
}
9494

9595
function getRowCells(currentCell: ReactScopeMethods) {
96-
const row = currentCell.getParent();
97-
if (row !== null && row.getProps().type === 'row') {
98-
const cells = row.getChildren();
96+
const row = currentCell.DO_NOT_USE_getParent();
97+
if (row !== null && row.DO_NOT_USE_getProps().type === 'row') {
98+
const cells = row.DO_NOT_USE_getChildren();
9999
if (cells !== null) {
100100
const [rowIndex, rowIndexWithColSpan] = getCellIndexes(
101101
cells,
@@ -108,11 +108,11 @@ function getRowCells(currentCell: ReactScopeMethods) {
108108
}
109109

110110
function getRows(currentCell: ReactScopeMethods) {
111-
const row = currentCell.getParent();
112-
if (row !== null && row.getProps().type === 'row') {
113-
const table = row.getParent();
114-
if (table !== null && table.getProps().type === 'table') {
115-
const rows = table.getChildren();
111+
const row = currentCell.DO_NOT_USE_getParent();
112+
if (row !== null && row.DO_NOT_USE_getProps().type === 'row') {
113+
const table = row.DO_NOT_USE_getParent();
114+
if (table !== null && table.DO_NOT_USE_getProps().type === 'table') {
115+
const rows = table.DO_NOT_USE_getChildren();
116116
if (rows !== null) {
117117
const columnIndex = rows.indexOf(row);
118118
return [rows, columnIndex];
@@ -127,11 +127,11 @@ function triggerNavigateOut(
127127
direction: 'left' | 'right' | 'up' | 'down',
128128
event,
129129
): void {
130-
const row = currentCell.getParent();
131-
if (row !== null && row.getProps().type === 'row') {
132-
const table = row.getParent();
130+
const row = currentCell.DO_NOT_USE_getParent();
131+
if (row !== null && row.DO_NOT_USE_getProps().type === 'row') {
132+
const table = row.DO_NOT_USE_getParent();
133133
if (table !== null) {
134-
const props = table.getProps();
134+
const props = table.DO_NOT_USE_getProps();
135135
const onKeyboardOut = props.onKeyboardOut;
136136
if (props.type === 'table' && typeof onKeyboardOut === 'function') {
137137
onKeyboardOut(direction, event);
@@ -143,11 +143,11 @@ function triggerNavigateOut(
143143
}
144144

145145
function getTableProps(currentCell: ReactScopeMethods): Object {
146-
const row = currentCell.getParent();
147-
if (row !== null && row.getProps().type === 'row') {
148-
const table = row.getParent();
146+
const row = currentCell.DO_NOT_USE_getParent();
147+
if (row !== null && row.DO_NOT_USE_getProps().type === 'row') {
148+
const table = row.DO_NOT_USE_getParent();
149149
if (table !== null) {
150-
return table.getProps();
150+
return table.DO_NOT_USE_getProps();
151151
}
152152
}
153153
return {};
@@ -207,12 +207,14 @@ export function createFocusTable(
207207
if (key === 'Tab') {
208208
const tabScopeQuery = getTableProps(currentCell).tabScopeQuery;
209209
if (tabScopeQuery) {
210-
const rowScope = currentCell.getParent();
210+
const rowScope = currentCell.DO_NOT_USE_getParent();
211211
if (rowScope) {
212-
const tableScope = rowScope.getParent();
212+
const tableScope = rowScope.DO_NOT_USE_getParent();
213213
if (tableScope) {
214214
const activeNode = document.activeElement;
215-
const nodes = tableScope.queryAllNodes(tabScopeQuery);
215+
const nodes = tableScope.DO_NOT_USE_queryAllNodes(
216+
tabScopeQuery,
217+
);
216218
for (let i = 0; i < nodes.length; i++) {
217219
const node = nodes[i];
218220
if (node !== activeNode) {

packages/react-interactions/accessibility/src/__tests__/TabbableScopeQuery-test.internal.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ describe('TabbableScopeQuery', () => {
3535
container = null;
3636
});
3737

38-
it('queryAllNodes() works as intended', () => {
38+
it('DO_NOT_USE_queryAllNodes() works as intended', () => {
3939
const scopeRef = React.createRef();
4040
const nodeRefA = React.createRef();
4141
const nodeRefB = React.createRef();
@@ -60,7 +60,7 @@ describe('TabbableScopeQuery', () => {
6060
}
6161

6262
ReactDOM.render(<Test />, container);
63-
let nodes = scopeRef.current.queryAllNodes(tabbableScopeQuery);
63+
let nodes = scopeRef.current.DO_NOT_USE_queryAllNodes(tabbableScopeQuery);
6464
expect(nodes).toEqual([
6565
nodeRefA.current,
6666
nodeRefB.current,

packages/react-interactions/accessibility/src/shared/getTabbableNodes.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ export default function getTabbableNodes(
1919
number,
2020
null | HTMLElement,
2121
] {
22-
const tabbableNodes = scope.queryAllNodes(scopeQuery);
22+
const tabbableNodes = scope.DO_NOT_USE_queryAllNodes(scopeQuery);
2323
if (tabbableNodes === null || tabbableNodes.length === 0) {
2424
return [null, null, null, 0, null];
2525
}

0 commit comments

Comments
 (0)