@selenium/atoms 4.52.0 → 4.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/README.md +56 -0
  2. package/dist/index.d.ts +4 -0
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +2 -0
  5. package/dist/index.js.map +1 -1
  6. package/dist/typescript/accessibility-snapshot-wire.d.ts +4 -0
  7. package/dist/typescript/accessibility-snapshot-wire.d.ts.map +1 -0
  8. package/dist/typescript/accessibility-snapshot-wire.js +18 -0
  9. package/dist/typescript/accessibility-snapshot-wire.js.map +1 -0
  10. package/dist/typescript/accessibility-snapshot.d.ts +3 -0
  11. package/dist/typescript/accessibility-snapshot.d.ts.map +1 -0
  12. package/dist/typescript/accessibility-snapshot.js +18 -0
  13. package/dist/typescript/accessibility-snapshot.js.map +1 -0
  14. package/dist/typescript/core/accessibility/accname.d.ts +6 -0
  15. package/dist/typescript/core/accessibility/accname.d.ts.map +1 -0
  16. package/dist/typescript/core/accessibility/accname.js +537 -0
  17. package/dist/typescript/core/accessibility/accname.js.map +1 -0
  18. package/dist/typescript/core/accessibility/context.d.ts +43 -0
  19. package/dist/typescript/core/accessibility/context.d.ts.map +1 -0
  20. package/dist/typescript/core/accessibility/context.js +49 -0
  21. package/dist/typescript/core/accessibility/context.js.map +1 -0
  22. package/dist/typescript/core/accessibility/hidden.d.ts +39 -0
  23. package/dist/typescript/core/accessibility/hidden.d.ts.map +1 -0
  24. package/dist/typescript/core/accessibility/hidden.js +216 -0
  25. package/dist/typescript/core/accessibility/hidden.js.map +1 -0
  26. package/dist/typescript/core/accessibility/roles.d.ts +28 -0
  27. package/dist/typescript/core/accessibility/roles.d.ts.map +1 -0
  28. package/dist/typescript/core/accessibility/roles.js +381 -0
  29. package/dist/typescript/core/accessibility/roles.js.map +1 -0
  30. package/dist/typescript/core/accessibility/snapshot.d.ts +13 -0
  31. package/dist/typescript/core/accessibility/snapshot.d.ts.map +1 -0
  32. package/dist/typescript/core/accessibility/snapshot.js +55 -0
  33. package/dist/typescript/core/accessibility/snapshot.js.map +1 -0
  34. package/dist/typescript/core/accessibility/states.d.ts +18 -0
  35. package/dist/typescript/core/accessibility/states.d.ts.map +1 -0
  36. package/dist/typescript/core/accessibility/states.js +215 -0
  37. package/dist/typescript/core/accessibility/states.js.map +1 -0
  38. package/dist/typescript/core/accessibility/tree.d.ts +10 -0
  39. package/dist/typescript/core/accessibility/tree.d.ts.map +1 -0
  40. package/dist/typescript/core/accessibility/tree.js +261 -0
  41. package/dist/typescript/core/accessibility/tree.js.map +1 -0
  42. package/dist/typescript/core/accessibility/types.d.ts +30 -0
  43. package/dist/typescript/core/accessibility/types.d.ts.map +1 -0
  44. package/dist/typescript/core/accessibility/types.js +18 -0
  45. package/dist/typescript/core/accessibility/types.js.map +1 -0
  46. package/dist/typescript/core/accessibility/value.d.ts +4 -0
  47. package/dist/typescript/core/accessibility/value.d.ts.map +1 -0
  48. package/dist/typescript/core/accessibility/value.js +83 -0
  49. package/dist/typescript/core/accessibility/value.js.map +1 -0
  50. package/dist/typescript/core/accessibility/wire.d.ts +57 -0
  51. package/dist/typescript/core/accessibility/wire.d.ts.map +1 -0
  52. package/dist/typescript/core/accessibility/wire.js +72 -0
  53. package/dist/typescript/core/accessibility/wire.js.map +1 -0
  54. package/index.ts +4 -0
  55. package/package.json +15 -1
  56. package/typescript/accessibility-snapshot-wire.ts +20 -0
  57. package/typescript/accessibility-snapshot.ts +21 -0
  58. package/typescript/core/accessibility/accname.ts +587 -0
  59. package/typescript/core/accessibility/context.ts +116 -0
  60. package/typescript/core/accessibility/hidden.ts +242 -0
  61. package/typescript/core/accessibility/roles.ts +410 -0
  62. package/typescript/core/accessibility/snapshot.ts +61 -0
  63. package/typescript/core/accessibility/states.ts +233 -0
  64. package/typescript/core/accessibility/tree.ts +306 -0
  65. package/typescript/core/accessibility/types.ts +52 -0
  66. package/typescript/core/accessibility/value.ts +89 -0
  67. package/typescript/core/accessibility/wire.ts +123 -0
@@ -0,0 +1,116 @@
1
+ // Licensed to the Software Freedom Conservancy (SFC) under one
2
+ // or more contributor license agreements. See the NOTICE file
3
+ // distributed with this work for additional information
4
+ // regarding copyright ownership. The SFC licenses this file
5
+ // to you under the Apache License, Version 2.0 (the
6
+ // "License"); you may not use this file except in compliance
7
+ // with the License. You may obtain a copy of the License at
8
+ //
9
+ // http://www.apache.org/licenses/LICENSE-2.0
10
+ //
11
+ // Unless required by applicable law or agreed to in writing,
12
+ // software distributed under the License is distributed on an
13
+ // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
+ // KIND, either express or implied. See the License for the
15
+ // specific language governing permissions and limitations
16
+ // under the License.
17
+ import type { HiddenState } from './hidden.js'
18
+ import { computeRole } from './roles.js'
19
+ import type { SnapshotOptions } from './types.js'
20
+
21
+ // State shared by one snapshot call. It lives exactly as long as the call:
22
+ // the snapshot is a copy taken at one point in time (ADR 18205 §1), and a
23
+ // cache that outlived it would hand back stale roles or names after the page
24
+ // changed an attribute, because element identity does not change with it.
25
+ // Nothing in the DOM can change during the synchronous walk, so memoising
26
+ // per-element results within the call is safe.
27
+ //
28
+ // Roles, hidden states and styles are cached because name computation asks
29
+ // for the roles, hidden-ness and display of descendants and of
30
+ // aria-labelledby targets that the walk also visits; names are cached
31
+ // because several nodes can reference the same element.
32
+ export interface SnapshotContext {
33
+ /** False turns the pruning of unnamed generic and presentational nodes off. */
34
+ readonly interestingOnly: boolean
35
+ readonly roles: Map<Element, string>
36
+ readonly hidden: Map<Element, HiddenState>
37
+ /** Whether an image map, by name, is rendered through some image that uses it; shared by all its areas. */
38
+ readonly imageMaps: Map<string, HiddenState>
39
+ readonly styles: Map<Element, Map<string, CSSStyleDeclaration | null>>
40
+ readonly names: Map<Element, NameResult>
41
+ readonly descriptions: Map<Element, string>
42
+ /** Text alternative per element as a descendant of something being named (the standard recursive traversal), which every enclosing content-named ancestor repeats. */
43
+ readonly descendantTexts: Map<Element, string>
44
+ /** Name-from-content text per element for the standard traversal. */
45
+ readonly contentTexts: Map<Element, string>
46
+ /** Text alternative per aria-labelledby / aria-describedby target, which many elements can reference. */
47
+ readonly referenceTexts: Map<Element, string>
48
+ /** Generated ::before and ::after text per element, read at most once. */
49
+ readonly generated: Map<Element, [string, string]>
50
+ /** Per tree scope (document or shadow root): whether any of its sheets can define generated content. */
51
+ readonly generatedScopes: Map<Node, boolean>
52
+ /** Elements already placed in the tree; aria-owns re-parenting must not place one twice. */
53
+ readonly placed: Set<Element>
54
+ /** aria-owns targets of each owner in the walked subtree, in attribute order. */
55
+ readonly owned: Map<Element, Element[]>
56
+ /** Every owned element, so it is skipped at its DOM position and placed under its owner. */
57
+ readonly claimed: Set<Element>
58
+ }
59
+
60
+ /** Where a name came from decides whether text below the node is repeated and whether title is free for the description. */
61
+ export type NameSource = 'none' | 'reference' | 'label' | 'native' | 'content' | 'title' | 'placeholder'
62
+
63
+ export interface NameResult {
64
+ readonly text: string
65
+ readonly source: NameSource
66
+ }
67
+
68
+ export function createContext(options?: SnapshotOptions): SnapshotContext {
69
+ return {
70
+ interestingOnly: options === undefined || options === null || options.interestingOnly !== false,
71
+ roles: new Map(),
72
+ hidden: new Map(),
73
+ imageMaps: new Map(),
74
+ styles: new Map(),
75
+ names: new Map(),
76
+ descriptions: new Map(),
77
+ descendantTexts: new Map(),
78
+ contentTexts: new Map(),
79
+ referenceTexts: new Map(),
80
+ generated: new Map(),
81
+ generatedScopes: new Map(),
82
+ placed: new Set(),
83
+ owned: new Map(),
84
+ claimed: new Set(),
85
+ }
86
+ }
87
+
88
+ export function roleOf(element: Element, context: SnapshotContext): string {
89
+ let role = context.roles.get(element)
90
+ if (role === undefined) {
91
+ // The role of a cell depends on its table's, which every cell would
92
+ // otherwise recompute; the lookup goes through this cache.
93
+ role = computeRole(element, (owner) => roleOf(owner, context))
94
+ context.roles.set(element, role)
95
+ }
96
+ return role
97
+ }
98
+
99
+ /**
100
+ * The computed style of an element, or of one of its pseudo-elements when
101
+ * `pseudo` is "::before" or "::after". Null when the element has no view.
102
+ */
103
+ export function styleOf(element: Element, context: SnapshotContext, pseudo = ''): CSSStyleDeclaration | null {
104
+ let perPseudo = context.styles.get(element)
105
+ if (!perPseudo) {
106
+ perPseudo = new Map()
107
+ context.styles.set(element, perPseudo)
108
+ }
109
+ let style = perPseudo.get(pseudo)
110
+ if (style === undefined) {
111
+ const view = element.ownerDocument.defaultView
112
+ style = view ? view.getComputedStyle(element, pseudo || null) : null
113
+ perPseudo.set(pseudo, style)
114
+ }
115
+ return style
116
+ }
@@ -0,0 +1,242 @@
1
+ // Licensed to the Software Freedom Conservancy (SFC) under one
2
+ // or more contributor license agreements. See the NOTICE file
3
+ // distributed with this work for additional information
4
+ // regarding copyright ownership. The SFC licenses this file
5
+ // to you under the Apache License, Version 2.0 (the
6
+ // "License"); you may not use this file except in compliance
7
+ // with the License. You may obtain a copy of the License at
8
+ //
9
+ // http://www.apache.org/licenses/LICENSE-2.0
10
+ //
11
+ // Unless required by applicable law or agreed to in writing,
12
+ // software distributed under the License is distributed on an
13
+ // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
+ // KIND, either express or implied. See the License for the
15
+ // specific language governing permissions and limitations
16
+ // under the License.
17
+
18
+ // "Hidden" in the accname sense (https://w3c.github.io/accname/#dfn-hidden):
19
+ // an element that is not rendered, or that has aria-hidden=true on itself or
20
+ // an ancestor. This is deliberately not bot.dom.isShown. WebDriver's
21
+ // displayedness also prunes zero-size, transparent and off-screen content,
22
+ // which assistive technology does reach; the "visually hidden" CSS pattern
23
+ // that screen-reader-only text relies on is built on exactly that difference.
24
+ //
25
+ // Ancestry follows the flat tree (slots and shadow hosts), because that is
26
+ // what gets rendered, not the light DOM.
27
+
28
+ import { SnapshotContext, styleOf } from './context.js'
29
+
30
+ const DOCUMENT_NODE = 9
31
+ const DOCUMENT_FRAGMENT_NODE = 11
32
+
33
+ /**
34
+ * What an element does to its own visibility, with no regard to ancestors:
35
+ * rendered it has a box
36
+ * self its own box is invisible but a descendant may set itself visible
37
+ * again (visibility is inherited, not a subtree switch)
38
+ * contents its own box is rendered but nothing below it is
39
+ * (content-visibility: hidden, which hidden="until-found" uses)
40
+ * subtree neither it nor anything below it is rendered
41
+ */
42
+ export type HiddenState = 'rendered' | 'self' | 'contents' | 'subtree'
43
+
44
+ // The flat-tree parent of a node, or one of two terminals.
45
+ const NOT_RENDERED: unique symbol = Symbol('not rendered')
46
+ type FlatTreeParent = Element | null | typeof NOT_RENDERED
47
+
48
+ function isAriaHidden(element: Element): boolean {
49
+ const value = element.getAttribute('aria-hidden')
50
+ return value !== null && value.trim().toLowerCase() === 'true'
51
+ }
52
+
53
+ // The UA stylesheet gives every area display: none; what renders it is the
54
+ // image whose usemap points at its map. So an area is as hidden as that image.
55
+ // The document-wide image lookup is done once per map name and snapshot, since
56
+ // every area of a map shares the answer.
57
+ function areaState(area: Element, context: SnapshotContext): HiddenState {
58
+ const map = area.closest('map')
59
+ const name = map ? map.getAttribute('name') : null
60
+ if (!name) {
61
+ return 'subtree'
62
+ }
63
+ const known = context.imageMaps.get(name)
64
+ if (known !== undefined) {
65
+ return known
66
+ }
67
+ let state: HiddenState = 'subtree'
68
+ const images = area.ownerDocument.querySelectorAll('img[usemap]')
69
+ for (let i = 0; i < images.length; i++) {
70
+ const image = images[i]
71
+ const usemap = (image.getAttribute('usemap') || '').replace(/^#/, '')
72
+ if (usemap === name && hiddenState(image, context) === 'rendered' && !isHiddenByAncestor(image, context)) {
73
+ state = 'rendered'
74
+ break
75
+ }
76
+ }
77
+ context.imageMaps.set(name, state)
78
+ return state
79
+ }
80
+
81
+ export function isClosedDetails(element: Element): boolean {
82
+ return element.localName === 'details' && !element.hasAttribute('open')
83
+ }
84
+
85
+ /**
86
+ * The parent that renders this node: its slot when it is assigned to one, the
87
+ * host when it sits directly in a shadow root, otherwise its DOM parent. Null
88
+ * at the document; NOT_RENDERED for nodes the flat tree leaves out (a child of
89
+ * a shadow host that no slot took, fallback content of a slot that has
90
+ * assigned nodes, anything detached or inside an inert fragment).
91
+ *
92
+ * A closed shadow root cannot be seen from outside: `shadowRoot` and
93
+ * `assignedSlot` are both null for its host's children, so those read as
94
+ * ordinary children of the host and are treated as rendered.
95
+ */
96
+ // An HTML slot element; an element merely named slot in another namespace
97
+ // has no assigned nodes to ask for.
98
+ function isSlot(element: Element): element is HTMLSlotElement {
99
+ return element.localName === 'slot' && 'assignedNodes' in element
100
+ }
101
+
102
+ function flatTreeParent(node: Element): FlatTreeParent {
103
+ const parent = node.parentNode
104
+ if (!parent) {
105
+ return NOT_RENDERED
106
+ }
107
+ if (node.assignedSlot) {
108
+ return node.assignedSlot
109
+ }
110
+ if (parent.nodeType === DOCUMENT_FRAGMENT_NODE) {
111
+ const host = (parent as ShadowRoot).host
112
+ return host ? host : NOT_RENDERED
113
+ }
114
+ if (parent.nodeType === DOCUMENT_NODE) {
115
+ return null
116
+ }
117
+ const parentElement = parent as Element
118
+ if (parentElement.shadowRoot) {
119
+ return NOT_RENDERED
120
+ }
121
+ if (isSlot(parentElement) && parentElement.assignedNodes().length > 0) {
122
+ return NOT_RENDERED
123
+ }
124
+ return parentElement
125
+ }
126
+
127
+ /**
128
+ * The nodes rendered as this element's children, in render order: the shadow
129
+ * root's children for a host, the assigned nodes (or the fallback while none
130
+ * are assigned) for a slot, otherwise the DOM children. Nested slots are
131
+ * flattened away, so a slot element never appears in the result.
132
+ *
133
+ * A closed shadow root cannot be seen, so its host's light children are
134
+ * returned as if they rendered; see flatTreeParent.
135
+ */
136
+ export function flatTreeChildren(element: Element): ArrayLike<Node> {
137
+ if (isSlot(element)) {
138
+ return element.assignedNodes({ flatten: true })
139
+ }
140
+ if (element.shadowRoot) {
141
+ return element.shadowRoot.childNodes
142
+ }
143
+ return element.childNodes
144
+ }
145
+
146
+ /**
147
+ * Children of a closed details element are not rendered, apart from its first
148
+ * summary. The browser does this through a UA shadow tree that is closed to
149
+ * script, so it has to be known here rather than read from the DOM.
150
+ */
151
+ export function isCollapsedDetailsContent(child: Element, parent: Element): boolean {
152
+ if (!isClosedDetails(parent)) {
153
+ return false
154
+ }
155
+ for (let sibling = parent.firstElementChild; sibling; sibling = sibling.nextElementSibling) {
156
+ if (sibling.localName === 'summary') {
157
+ return sibling !== child
158
+ }
159
+ }
160
+ return true
161
+ }
162
+
163
+ /**
164
+ * See HiddenState. Ancestors are not consulted; isHidden does that. Cached
165
+ * per element in the context: the walk, name-from-content and reference
166
+ * resolution all ask about the same elements.
167
+ */
168
+ export function hiddenState(element: Element, context: SnapshotContext): HiddenState {
169
+ let state = context.hidden.get(element)
170
+ if (state === undefined) {
171
+ state = computeHiddenState(element, context)
172
+ context.hidden.set(element, state)
173
+ }
174
+ return state
175
+ }
176
+
177
+ function computeHiddenState(element: Element, context: SnapshotContext): HiddenState {
178
+ // Inert content is still painted, but browsers leave it out of the
179
+ // accessibility tree along with everything it contains.
180
+ if (isAriaHidden(element) || element.hasAttribute('inert')) {
181
+ return 'subtree'
182
+ }
183
+ // With scripting enabled a noscript element renders nothing, but Chromium
184
+ // decides that in layout rather than in its UA stylesheet, so its computed
185
+ // display still reads inline. This atom only ever runs as script.
186
+ if (element.localName === 'noscript') {
187
+ return 'subtree'
188
+ }
189
+ if (element.localName === 'area') {
190
+ return areaState(element, context)
191
+ }
192
+ const style = styleOf(element, context)
193
+ // No view (an inert template fragment) and a detached element (empty
194
+ // computed values) are both unrendered.
195
+ if (!style || style.display === '' || style.display === 'none') {
196
+ return 'subtree'
197
+ }
198
+ const visibility = style.visibility
199
+ const invisible = visibility === 'hidden' || visibility === 'collapse'
200
+ const contentsSkipped = style.getPropertyValue('content-visibility') === 'hidden'
201
+ if (invisible && contentsSkipped) {
202
+ return 'subtree'
203
+ }
204
+ if (contentsSkipped) {
205
+ return 'contents'
206
+ }
207
+ if (invisible) {
208
+ return 'self'
209
+ }
210
+ return 'rendered'
211
+ }
212
+
213
+ /** Whether an ancestor in the flat tree hides this element, whatever the element does itself. */
214
+ export function isHiddenByAncestor(element: Element, context: SnapshotContext): boolean {
215
+ let child = element
216
+ for (;;) {
217
+ const parent = flatTreeParent(child)
218
+ if (parent === NOT_RENDERED) {
219
+ return true
220
+ }
221
+ if (parent === null) {
222
+ return false
223
+ }
224
+ const state = hiddenState(parent, context)
225
+ if (isCollapsedDetailsContent(child, parent) || state === 'subtree' || state === 'contents') {
226
+ return true
227
+ }
228
+ child = parent
229
+ }
230
+ }
231
+
232
+ /** Whether the element is hidden in the accname sense. */
233
+ export function isHidden(element: Element, context: SnapshotContext): boolean {
234
+ const own = hiddenState(element, context)
235
+ if (own === 'self' || own === 'subtree') {
236
+ return true
237
+ }
238
+ // Visibility is inherited, so the element's own computed value above already
239
+ // accounts for ancestors that set it; only subtree-wide hiding is checked
240
+ // on the way up.
241
+ return isHiddenByAncestor(element, context)
242
+ }