Skip to content

Commit cc0c7a0

Browse files
committed
refactor(android): split clickable and focusable instead of collapsing them
`hittable: clickable ?? focusable` collapsed two independent Android facts and made behavior depend on how a producer encodes a false attribute. The snapshot helper omits `clickable`; stock UiAutomator writes `clickable="false"`. For one focusable control those encodings gave opposite answers — verified: identical trees pruned differently and projected opposite `hittable` values. No comment can hold an invariant the representation contradicts, which is what the previous two commits tried to do. The tree now stores `clickable` and `focusable` as separate non-optional booleans, and every decision reads a named predicate: isTouchTarget, isFocusTarget, isAgentTarget, hasSemanticContent, hasDirectOcclusionEvidence, hasDescendantOcclusionEvidence, isPresentationLeaf. `canCoverSibling` consumes one derived classification (hasOcclusionEvidence) rather than choosing between raw attributes, so the self-versus-descendant substitution that caused the last review round is no longer expressible. Removing `hittable` from the tree type made the typechecker find every construction site; the public field is derived once at projection from isAgentTarget. Behavior change: a focusable, non-clickable control encoded by stock UiAutomator now projects hittable=true and participates in occlusion, matching what the helper backend already did for the same control. The Android TV test asserted the old encoding-specific value; it now asserts inclusion plus the unified projection. One encoding-parity regression replaces the patch-specific test added last round.
1 parent c87f621 commit cc0c7a0

3 files changed

Lines changed: 108 additions & 84 deletions

File tree

‎src/__tests__/test-utils/android-ui-hierarchy-fixtures.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,9 @@ function rawFixtureToTreeNode(raw: RawSnapshotNode): AndroidUiHierarchy {
3131
identifier: raw.identifier ?? null,
3232
packageName: raw.bundleId ?? null,
3333
rect: raw.rect,
34-
hittable: raw.hittable,
34+
// Fixtures speak the public projection; split it back into the two facts the tree stores.
35+
clickable: raw.hittable === true,
36+
focusable: false,
3537
visibleToUser: raw.visibleToUser,
3638
depth: 0,
3739
children: [],
@@ -45,6 +47,8 @@ function rawFixtureToAndroidTree(rawNodes: RawSnapshotNode[]): AndroidUiHierarch
4547
value: null,
4648
identifier: null,
4749
packageName: null,
50+
clickable: false,
51+
focusable: false,
4852
depth: -1,
4953
children: [],
5054
};

‎src/platforms/android/__tests__/ui-hierarchy.test.ts‎

Lines changed: 37 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,43 @@ test('parseUiHierarchy keeps focused non-clickable Android TV nodes in interacti
243243
const focused = result.nodes.find((node) => node.label === 'Featured');
244244

245245
assert.equal(focused?.focused, true);
246-
assert.equal(focused?.hittable, false);
246+
// A D-pad control an agent can drive is a target regardless of which input model reaches it.
247+
assert.equal(focused?.hittable, true);
248+
});
249+
250+
test('parseUiHierarchy reads an omitted clickable attribute the same as clickable="false"', () => {
251+
// The snapshot helper omits false attributes; stock UiAutomator writes them out. Those are two
252+
// encodings of one control, so every derived answer — public projection and pruning alike — has
253+
// to agree. Reading an absent attribute as a value is what made them diverge.
254+
const tree = (clickable: string) => `<hierarchy>
255+
<node class="android.widget.FrameLayout" bounds="[0,0][390,844]" visible-to-user="true" drawing-order="0">
256+
<node class="android.view.ViewGroup" bounds="[0,0][390,844]" visible-to-user="true" drawing-order="2">
257+
<node class="android.widget.TextView" text="Foreground tile" bounds="[24,120][366,200]" enabled="true" visible-to-user="true" focusable="true" ${clickable} drawing-order="1"/>
258+
</node>
259+
<node class="android.view.ViewGroup" bounds="[0,0][390,844]" visible-to-user="true" drawing-order="1">
260+
<node class="android.widget.TextView" text="Background row" bounds="[0,220][280,280]" enabled="true" visible-to-user="true" focusable="true" ${clickable} drawing-order="1"/>
261+
</node>
262+
</node>
263+
</hierarchy>`;
264+
265+
const omitted = parseUiHierarchy(tree(''), 800, { raw: true });
266+
const explicitFalse = parseUiHierarchy(tree('clickable="false"'), 800, { raw: true });
267+
268+
assert.deepEqual(
269+
explicitFalse.nodes.map((node) => [node.label, node.hittable]),
270+
omitted.nodes.map((node) => [node.label, node.hittable]),
271+
);
272+
// Both encodings must also agree that the foreground surface covers the background one.
273+
for (const result of [omitted, explicitFalse]) {
274+
assert.equal(
275+
result.nodes.some((node) => node.label === 'Foreground tile'),
276+
true,
277+
);
278+
assert.equal(
279+
result.nodes.some((node) => node.label === 'Background row'),
280+
false,
281+
);
282+
}
247283
});
248284

249285
test('parseUiHierarchy prunes Android nodes that are not visible to the user in raw snapshots', () => {
@@ -484,32 +520,6 @@ test('parseUiHierarchy keeps app content under a childless focusable full-screen
484520
);
485521
});
486522

487-
test('parseUiHierarchy suppresses a covered target under a focusable-only foreground surface', () => {
488-
// Helper-shaped: the snapshot helper emits clickable/focusable only when true, so a D-pad/TV
489-
// control arrives as focusable="true" with no clickable attribute at all. A foreground surface
490-
// built from those still covers, or background targets stay selectable behind it.
491-
const xml = `<hierarchy>
492-
<node class="android.widget.FrameLayout" bounds="[0,0][390,844]" visible-to-user="true" drawing-order="0">
493-
<node class="android.view.ViewGroup" bounds="[0,0][390,844]" visible-to-user="true" drawing-order="2">
494-
<node class="android.widget.Button" text="Foreground tile" bounds="[24,120][366,200]" enabled="true" visible-to-user="true" focusable="true" drawing-order="1"/>
495-
</node>
496-
<node class="android.view.ViewGroup" bounds="[0,0][390,844]" visible-to-user="true" drawing-order="1">
497-
<node class="android.widget.Button" text="Background row" bounds="[0,220][280,280]" enabled="true" visible-to-user="true" focusable="true" drawing-order="1"/>
498-
</node>
499-
</node>
500-
</hierarchy>`;
501-
502-
const result = parseUiHierarchy(xml, 800, { raw: true });
503-
assert.equal(
504-
result.nodes.some((node) => node.label === 'Foreground tile'),
505-
true,
506-
);
507-
assert.equal(
508-
result.nodes.some((node) => node.label === 'Background row'),
509-
false,
510-
);
511-
});
512-
513523
test('parseUiHierarchy keeps an overlapped text leaf drawn inside a composite widget sibling', () => {
514524
// Telegram renders the "+" of "+1" as a TextView sitting inside the country-code EditText's box.
515525
const xml = `<hierarchy>

‎src/platforms/android/ui-hierarchy.ts‎

Lines changed: 66 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@ function walkUiHierarchyNode(
193193
const currentIndex = include
194194
? appendAndroidSnapshotNode(state, node, parentIndex, systemChrome)
195195
: parentIndex;
196-
const nextAncestorHittable = ancestorHittable || Boolean(node.hittable);
196+
const nextAncestorHittable = ancestorHittable || isAgentTarget(node);
197197
const nextAncestorCollection = ancestorCollection || isCollectionContainerType(node.type);
198198
for (const child of node.children) {
199199
walkUiHierarchyNode(
@@ -232,7 +232,7 @@ function appendAndroidSnapshotNode(
232232
enabled: node.enabled,
233233
focused: node.focused,
234234
visibleToUser: node.visibleToUser,
235-
hittable: node.hittable,
235+
hittable: isAgentTarget(node) || undefined,
236236
depth: compactedAndroidNodeDepth(state.nodes, parentIndex),
237237
parentIndex,
238238
...(node.hiddenContentAbove ? { hiddenContentAbove: true } : {}),
@@ -255,7 +255,7 @@ function hasInteractiveDescendant(state: AndroidSnapshotBuildState, node: Androi
255255
for (const child of node.children) {
256256
if (
257257
child.visibleToUser !== false &&
258-
(child.hittable || hasInteractiveDescendant(state, child))
258+
(isAgentTarget(child) || hasInteractiveDescendant(state, child))
259259
) {
260260
state.interactiveDescendantMemo.set(node, true);
261261
return true;
@@ -421,8 +421,11 @@ export type AndroidUiHierarchy = {
421421
visibleToUser?: boolean;
422422
drawingOrder?: number;
423423
focused?: boolean;
424-
hittable?: boolean;
425-
clickable?: boolean;
424+
// Two independent facts, never collapsed, and never undefined: the helper omits false attributes
425+
// while stock UiAutomator writes them out, so reading an absent attribute as a value gave two
426+
// encodings of one control opposite answers.
427+
clickable: boolean;
428+
focusable: boolean;
426429
depth: number;
427430
parentIndex?: number;
428431
hiddenContentAbove?: boolean;
@@ -467,6 +470,8 @@ export function parseUiHierarchyTree(xml: string): AndroidUiHierarchy {
467470
value: null,
468471
identifier: null,
469472
packageName: null,
473+
clickable: false,
474+
focusable: false,
470475
depth: -1,
471476
children: [],
472477
};
@@ -493,8 +498,8 @@ export function parseUiHierarchyTree(xml: string): AndroidUiHierarchy {
493498
focused: attrs.focused,
494499
visibleToUser: attrs.visibleToUser,
495500
drawingOrder: attrs.drawingOrder,
496-
hittable: attrs.clickable ?? attrs.focusable,
497-
clickable: attrs.clickable,
501+
clickable: attrs.clickable === true,
502+
focusable: attrs.focusable === true,
498503
scrollable: attrs.scrollable,
499504
canScrollForward: attrs.canScrollForward,
500505
canScrollBackward: attrs.canScrollBackward,
@@ -525,6 +530,53 @@ export function parseUiHierarchyTree(xml: string): AndroidUiHierarchy {
525530
return root;
526531
}
527532

533+
/** A node a touch can act on. */
534+
function isTouchTarget(node: AndroidNode): boolean {
535+
return node.clickable;
536+
}
537+
538+
/** A node D-pad/keyboard traversal can land on. Normal for TV controls, which are rarely clickable. */
539+
function isFocusTarget(node: AndroidNode): boolean {
540+
return node.focusable || node.focused === true;
541+
}
542+
543+
/** A node an agent can drive by either input model. This is what the public `hittable` projects. */
544+
function isAgentTarget(node: AndroidNode): boolean {
545+
return isTouchTarget(node) || isFocusTarget(node);
546+
}
547+
548+
/** Text or an address an agent can read or select by. */
549+
function hasSemanticContent(node: AndroidNode): boolean {
550+
return hasMeaningfulLabel(node) || hasMeaningfulIdentifier(node);
551+
}
552+
553+
/** Focusability is traversal, not paint, so it is not evidence a node hides anything (#1733). */
554+
function hasDirectOcclusionEvidence(node: AndroidNode): boolean {
555+
return node.visibleToUser !== false && (isTouchTarget(node) || hasSemanticContent(node));
556+
}
557+
558+
/** Evidence the node is a real surface because it contains something an agent could drive. */
559+
function hasDescendantOcclusionEvidence(node: AndroidNode, state: AndroidTreePruneState): boolean {
560+
const cached = state.actionableContentMemo.get(node);
561+
if (cached !== undefined) return cached;
562+
const result = node.children.some(
563+
(child) =>
564+
child.visibleToUser !== false &&
565+
(isAgentTarget(child) || hasDescendantOcclusionEvidence(child, state)),
566+
);
567+
state.actionableContentMemo.set(node, result);
568+
return result;
569+
}
570+
571+
/**
572+
* A childless sibling that only presents: an RN screen-level testID, or a label drawn inside a
573+
* higher sibling's box (Telegram's `+` over the country-code EditText). Geometry cannot tell a
574+
* transparent overlay from an opaque one, and exempting a leaf cannot resurrect a covered surface.
575+
*/
576+
function isPresentationLeaf(node: AndroidNode): boolean {
577+
return node.children.length === 0 && !isAgentTarget(node) && hasSemanticContent(node);
578+
}
579+
528580
function pruneAndroidInvisibleSubtrees(node: AndroidNode): void {
529581
let keptCount = 0;
530582
for (const child of node.children) {
@@ -556,24 +608,10 @@ function shouldKeepAndroidSibling(
556608
coveringCandidates: AndroidCoveringCandidate[],
557609
): boolean {
558610
return (
559-
isUncondemnableLeaf(node) || !isCoveredByHigherDrawingOrderSibling(node, coveringCandidates)
611+
isPresentationLeaf(node) || !isCoveredByHigherDrawingOrderSibling(node, coveringCandidates)
560612
);
561613
}
562614

563-
/**
564-
* A childless, non-hittable sibling that announces something of its own: the screen-level testID RN
565-
* emits beside its rendered navigator, or a composite widget's label drawn inside a higher sibling's
566-
* box (Telegram renders the `+` of `+1` as a TextView overlapping the country-code EditText).
567-
* Drawing order and geometry cannot tell a transparent overlay from an opaque one, and text an agent
568-
* never sees is the one loss it cannot recover from. Staying on the `hittable` contract keeps a
569-
* genuinely covered affordance condemned; exempting a leaf is bounded — it can never resurrect a
570-
* covered surface.
571-
*/
572-
function isUncondemnableLeaf(node: AndroidNode): boolean {
573-
if (node.children.length > 0 || node.hittable) return false;
574-
return hasMeaningfulIdentifier(node) || hasMeaningfulLabel(node);
575-
}
576-
577615
function isCoveredByHigherDrawingOrderSibling(
578616
node: AndroidNode,
579617
coveringCandidates: AndroidCoveringCandidate[],
@@ -605,47 +643,20 @@ function canCoverSibling(
605643
node.visibleToUser !== false &&
606644
node.drawingOrder !== undefined &&
607645
hasPositiveRect(node) &&
608-
(hasOwnAgentVisibleContent(node) || hasActionableDescendant(node, state))
646+
hasOcclusionEvidence(node, state)
609647
);
610648
}
611649

612-
/**
613-
* Whether this node presents something *of its own*: an affordance to act on, something to announce,
614-
* or an address to select by. Keyed on `clickable` rather than `hittable` because `hittable` falls
615-
* back to `focusable`, and a node that is only focusable — no text, no id, and (per `canCoverSibling`)
616-
* no actionable descendant — offers an agent nothing to see or target, so it cannot be the reason a
617-
* sibling is hidden. Telegram wraps every screen in exactly such a full-screen View (#1733).
618-
*
619-
* This is self-classification only. `hasActionableDescendant` deliberately stays on `hittable`: a
620-
* surface *containing* focusable-only controls (the norm on D-pad/TV) is a real covering surface.
621-
*/
622-
function hasOwnAgentVisibleContent(node: AndroidNode): boolean {
623-
if (node.visibleToUser === false) return false;
624-
return node.clickable === true || hasMeaningfulLabel(node) || hasMeaningfulIdentifier(node);
650+
/** The single occlusion classification. Covering is never re-derived from a raw attribute. */
651+
function hasOcclusionEvidence(node: AndroidNode, state: AndroidTreePruneState): boolean {
652+
return hasDirectOcclusionEvidence(node) || hasDescendantOcclusionEvidence(node, state);
625653
}
626654

627655
function hasMeaningfulLabel(node: AndroidNode): boolean {
628656
const label = node.label?.trim() ?? '';
629657
return Boolean(label && !isGenericAndroidId(label));
630658
}
631659

632-
function hasActionableDescendant(node: AndroidNode, state: AndroidTreePruneState): boolean {
633-
const cached = state.actionableContentMemo.get(node);
634-
if (cached !== undefined) return cached;
635-
636-
// Descendant classification stays on `hittable`. The helper emits clickable/focusable only when
637-
// true, so a focusable-only control parses as clickable=undefined, hittable=true — and D-pad/TV
638-
// surfaces are built almost entirely from those. Narrowing this to `clickable` would stop such a
639-
// foreground surface from covering, leaving background targets selectable behind it.
640-
const result = node.children.some(
641-
(child) =>
642-
child.visibleToUser !== false &&
643-
(Boolean(child.hittable) || hasActionableDescendant(child, state)),
644-
);
645-
state.actionableContentMemo.set(node, result);
646-
return result;
647-
}
648-
649660
function hasPositiveRect(node: AndroidNode): node is AndroidNode & { rect: Rect } {
650661
return Boolean(node.rect && node.rect.width > 0 && node.rect.height > 0);
651662
}
@@ -776,8 +787,7 @@ function shouldIncludeInteractiveAndroidNode(
776787
ancestorCollection: boolean,
777788
): boolean {
778789
if (hasNonPositiveRect(node)) return false;
779-
if (node.focused) return true;
780-
if (node.hittable) return true;
790+
if (isAgentTarget(node)) return true;
781791
if (isScrollableType(info.type) && descendantHittable) return true;
782792
return shouldIncludeInteractiveProxyNode(
783793
info,
@@ -808,7 +818,7 @@ function shouldIncludeStructuralAndroidNode(
808818
info: AndroidNodeInclusionInfo,
809819
descendantHittable: boolean,
810820
): boolean {
811-
if (node.hittable) return true;
821+
if (isAgentTarget(node)) return true;
812822
if (info.hasMeaningfulText) return true;
813823
if (info.hasMeaningfulId) return true;
814824
return descendantHittable;

0 commit comments

Comments
 (0)