@selenium/atoms 4.51.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 (392) hide show
  1. package/README.md +56 -0
  2. package/dist/index.d.ts +44 -0
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +42 -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/active-element.d.ts +2 -0
  15. package/dist/typescript/active-element.d.ts.map +1 -0
  16. package/dist/typescript/active-element.js +19 -0
  17. package/dist/typescript/active-element.js.map +1 -0
  18. package/dist/typescript/clear-local-storage.d.ts +3 -0
  19. package/dist/typescript/clear-local-storage.d.ts.map +1 -0
  20. package/dist/typescript/clear-local-storage.js +25 -0
  21. package/dist/typescript/clear-local-storage.js.map +1 -0
  22. package/dist/typescript/clear-session-storage.d.ts +3 -0
  23. package/dist/typescript/clear-session-storage.d.ts.map +1 -0
  24. package/dist/typescript/clear-session-storage.js +25 -0
  25. package/dist/typescript/clear-session-storage.js.map +1 -0
  26. package/dist/typescript/clear.d.ts +3 -0
  27. package/dist/typescript/clear.d.ts.map +1 -0
  28. package/dist/typescript/clear.js +67 -0
  29. package/dist/typescript/clear.js.map +1 -0
  30. package/dist/typescript/click.d.ts +4 -0
  31. package/dist/typescript/click.d.ts.map +1 -0
  32. package/dist/typescript/click.js +52 -0
  33. package/dist/typescript/click.js.map +1 -0
  34. package/dist/typescript/core/accessibility/accname.d.ts +6 -0
  35. package/dist/typescript/core/accessibility/accname.d.ts.map +1 -0
  36. package/dist/typescript/core/accessibility/accname.js +537 -0
  37. package/dist/typescript/core/accessibility/accname.js.map +1 -0
  38. package/dist/typescript/core/accessibility/context.d.ts +43 -0
  39. package/dist/typescript/core/accessibility/context.d.ts.map +1 -0
  40. package/dist/typescript/core/accessibility/context.js +49 -0
  41. package/dist/typescript/core/accessibility/context.js.map +1 -0
  42. package/dist/typescript/core/accessibility/hidden.d.ts +39 -0
  43. package/dist/typescript/core/accessibility/hidden.d.ts.map +1 -0
  44. package/dist/typescript/core/accessibility/hidden.js +216 -0
  45. package/dist/typescript/core/accessibility/hidden.js.map +1 -0
  46. package/dist/typescript/core/accessibility/roles.d.ts +28 -0
  47. package/dist/typescript/core/accessibility/roles.d.ts.map +1 -0
  48. package/dist/typescript/core/accessibility/roles.js +381 -0
  49. package/dist/typescript/core/accessibility/roles.js.map +1 -0
  50. package/dist/typescript/core/accessibility/snapshot.d.ts +13 -0
  51. package/dist/typescript/core/accessibility/snapshot.d.ts.map +1 -0
  52. package/dist/typescript/core/accessibility/snapshot.js +55 -0
  53. package/dist/typescript/core/accessibility/snapshot.js.map +1 -0
  54. package/dist/typescript/core/accessibility/states.d.ts +18 -0
  55. package/dist/typescript/core/accessibility/states.d.ts.map +1 -0
  56. package/dist/typescript/core/accessibility/states.js +215 -0
  57. package/dist/typescript/core/accessibility/states.js.map +1 -0
  58. package/dist/typescript/core/accessibility/tree.d.ts +10 -0
  59. package/dist/typescript/core/accessibility/tree.d.ts.map +1 -0
  60. package/dist/typescript/core/accessibility/tree.js +261 -0
  61. package/dist/typescript/core/accessibility/tree.js.map +1 -0
  62. package/dist/typescript/core/accessibility/types.d.ts +30 -0
  63. package/dist/typescript/core/accessibility/types.d.ts.map +1 -0
  64. package/dist/typescript/core/accessibility/types.js +18 -0
  65. package/dist/typescript/core/accessibility/types.js.map +1 -0
  66. package/dist/typescript/core/accessibility/value.d.ts +4 -0
  67. package/dist/typescript/core/accessibility/value.d.ts.map +1 -0
  68. package/dist/typescript/core/accessibility/value.js +83 -0
  69. package/dist/typescript/core/accessibility/value.js.map +1 -0
  70. package/dist/typescript/core/accessibility/wire.d.ts +57 -0
  71. package/dist/typescript/core/accessibility/wire.d.ts.map +1 -0
  72. package/dist/typescript/core/accessibility/wire.js +72 -0
  73. package/dist/typescript/core/accessibility/wire.js.map +1 -0
  74. package/dist/typescript/core/attribute.d.ts +3 -0
  75. package/dist/typescript/core/attribute.d.ts.map +1 -0
  76. package/dist/typescript/core/attribute.js +60 -0
  77. package/dist/typescript/core/attribute.js.map +1 -0
  78. package/dist/typescript/core/color.d.ts +2 -0
  79. package/dist/typescript/core/color.d.ts.map +1 -0
  80. package/dist/typescript/core/color.js +248 -0
  81. package/dist/typescript/core/color.js.map +1 -0
  82. package/dist/typescript/core/editable.d.ts +5 -0
  83. package/dist/typescript/core/editable.d.ts.map +1 -0
  84. package/dist/typescript/core/editable.js +55 -0
  85. package/dist/typescript/core/editable.js.map +1 -0
  86. package/dist/typescript/core/element.d.ts +6 -0
  87. package/dist/typescript/core/element.d.ts.map +1 -0
  88. package/dist/typescript/core/element.js +97 -0
  89. package/dist/typescript/core/element.js.map +1 -0
  90. package/dist/typescript/core/enabled.d.ts +2 -0
  91. package/dist/typescript/core/enabled.d.ts.map +1 -0
  92. package/dist/typescript/core/enabled.js +69 -0
  93. package/dist/typescript/core/enabled.js.map +1 -0
  94. package/dist/typescript/core/error.d.ts +13 -0
  95. package/dist/typescript/core/error.d.ts.map +1 -0
  96. package/dist/typescript/core/error.js +40 -0
  97. package/dist/typescript/core/error.js.map +1 -0
  98. package/dist/typescript/core/events.d.ts +91 -0
  99. package/dist/typescript/core/events.d.ts.map +1 -0
  100. package/dist/typescript/core/events.js +131 -0
  101. package/dist/typescript/core/events.js.map +1 -0
  102. package/dist/typescript/core/focus.d.ts +4 -0
  103. package/dist/typescript/core/focus.d.ts.map +1 -0
  104. package/dist/typescript/core/focus.js +88 -0
  105. package/dist/typescript/core/focus.js.map +1 -0
  106. package/dist/typescript/core/focusable.d.ts +2 -0
  107. package/dist/typescript/core/focusable.d.ts.map +1 -0
  108. package/dist/typescript/core/focusable.js +36 -0
  109. package/dist/typescript/core/focusable.js.map +1 -0
  110. package/dist/typescript/core/form.d.ts +2 -0
  111. package/dist/typescript/core/form.d.ts.map +1 -0
  112. package/dist/typescript/core/form.js +76 -0
  113. package/dist/typescript/core/form.js.map +1 -0
  114. package/dist/typescript/core/frame.d.ts +8 -0
  115. package/dist/typescript/core/frame.d.ts.map +1 -0
  116. package/dist/typescript/core/frame.js +95 -0
  117. package/dist/typescript/core/frame.js.map +1 -0
  118. package/dist/typescript/core/geometry.d.ts +28 -0
  119. package/dist/typescript/core/geometry.d.ts.map +1 -0
  120. package/dist/typescript/core/geometry.js +134 -0
  121. package/dist/typescript/core/geometry.js.map +1 -0
  122. package/dist/typescript/core/inject.d.ts +21 -0
  123. package/dist/typescript/core/inject.d.ts.map +1 -0
  124. package/dist/typescript/core/inject.js +282 -0
  125. package/dist/typescript/core/inject.js.map +1 -0
  126. package/dist/typescript/core/interactable.d.ts +2 -0
  127. package/dist/typescript/core/interactable.d.ts.map +1 -0
  128. package/dist/typescript/core/interactable.js +27 -0
  129. package/dist/typescript/core/interactable.js.map +1 -0
  130. package/dist/typescript/core/keyboard.d.ts +15 -0
  131. package/dist/typescript/core/keyboard.d.ts.map +1 -0
  132. package/dist/typescript/core/keyboard.js +356 -0
  133. package/dist/typescript/core/keyboard.js.map +1 -0
  134. package/dist/typescript/core/keys.d.ts +65 -0
  135. package/dist/typescript/core/keys.d.ts.map +1 -0
  136. package/dist/typescript/core/keys.js +125 -0
  137. package/dist/typescript/core/keys.js.map +1 -0
  138. package/dist/typescript/core/locators.d.ts +6 -0
  139. package/dist/typescript/core/locators.d.ts.map +1 -0
  140. package/dist/typescript/core/locators.js +610 -0
  141. package/dist/typescript/core/locators.js.map +1 -0
  142. package/dist/typescript/core/mouse.d.ts +17 -0
  143. package/dist/typescript/core/mouse.d.ts.map +1 -0
  144. package/dist/typescript/core/mouse.js +186 -0
  145. package/dist/typescript/core/mouse.js.map +1 -0
  146. package/dist/typescript/core/overflow.d.ts +5 -0
  147. package/dist/typescript/core/overflow.d.ts.map +1 -0
  148. package/dist/typescript/core/overflow.js +133 -0
  149. package/dist/typescript/core/overflow.js.map +1 -0
  150. package/dist/typescript/core/scroll.d.ts +3 -0
  151. package/dist/typescript/core/scroll.d.ts.map +1 -0
  152. package/dist/typescript/core/scroll.js +77 -0
  153. package/dist/typescript/core/scroll.js.map +1 -0
  154. package/dist/typescript/core/shown.d.ts +3 -0
  155. package/dist/typescript/core/shown.d.ts.map +1 -0
  156. package/dist/typescript/core/shown.js +190 -0
  157. package/dist/typescript/core/shown.js.map +1 -0
  158. package/dist/typescript/core/storage.d.ts +14 -0
  159. package/dist/typescript/core/storage.d.ts.map +1 -0
  160. package/dist/typescript/core/storage.js +98 -0
  161. package/dist/typescript/core/storage.js.map +1 -0
  162. package/dist/typescript/core/style.d.ts +2 -0
  163. package/dist/typescript/core/style.d.ts.map +1 -0
  164. package/dist/typescript/core/style.js +32 -0
  165. package/dist/typescript/core/style.js.map +1 -0
  166. package/dist/typescript/core/useragent.d.ts +3 -0
  167. package/dist/typescript/core/useragent.d.ts.map +1 -0
  168. package/dist/typescript/core/useragent.js +31 -0
  169. package/dist/typescript/core/useragent.js.map +1 -0
  170. package/dist/typescript/default-content.d.ts +2 -0
  171. package/dist/typescript/default-content.d.ts.map +1 -0
  172. package/dist/typescript/default-content.js +20 -0
  173. package/dist/typescript/default-content.js.map +1 -0
  174. package/dist/typescript/execute-async-script.d.ts +2 -0
  175. package/dist/typescript/execute-async-script.d.ts.map +1 -0
  176. package/dist/typescript/execute-async-script.js +20 -0
  177. package/dist/typescript/execute-async-script.js.map +1 -0
  178. package/dist/typescript/execute-script.d.ts +2 -0
  179. package/dist/typescript/execute-script.d.ts.map +1 -0
  180. package/dist/typescript/execute-script.js +20 -0
  181. package/dist/typescript/execute-script.js.map +1 -0
  182. package/dist/typescript/find-element-fragment.d.ts +8 -0
  183. package/dist/typescript/find-element-fragment.d.ts.map +1 -0
  184. package/dist/typescript/find-element-fragment.js +39 -0
  185. package/dist/typescript/find-element-fragment.js.map +1 -0
  186. package/dist/typescript/find-element.d.ts +2 -0
  187. package/dist/typescript/find-element.d.ts.map +1 -0
  188. package/dist/typescript/find-element.js +18 -0
  189. package/dist/typescript/find-element.js.map +1 -0
  190. package/dist/typescript/find-elements.d.ts +1 -2
  191. package/dist/typescript/find-elements.d.ts.map +1 -1
  192. package/dist/typescript/find-elements.js +1 -289
  193. package/dist/typescript/find-elements.js.map +1 -1
  194. package/dist/typescript/frame-by-id-or-name.d.ts +2 -0
  195. package/dist/typescript/frame-by-id-or-name.d.ts.map +1 -0
  196. package/dist/typescript/frame-by-id-or-name.js +22 -0
  197. package/dist/typescript/frame-by-id-or-name.js.map +1 -0
  198. package/dist/typescript/frame-by-index.d.ts +2 -0
  199. package/dist/typescript/frame-by-index.d.ts.map +1 -0
  200. package/dist/typescript/frame-by-index.js +19 -0
  201. package/dist/typescript/frame-by-index.js.map +1 -0
  202. package/dist/typescript/get-attribute-value.d.ts +2 -0
  203. package/dist/typescript/get-attribute-value.d.ts.map +1 -0
  204. package/dist/typescript/get-attribute-value.js +22 -0
  205. package/dist/typescript/get-attribute-value.js.map +1 -0
  206. package/dist/typescript/get-effective-style.d.ts +3 -0
  207. package/dist/typescript/get-effective-style.d.ts.map +1 -0
  208. package/dist/typescript/get-effective-style.js +84 -0
  209. package/dist/typescript/get-effective-style.js.map +1 -0
  210. package/dist/typescript/get-element-from-cache.d.ts +2 -0
  211. package/dist/typescript/get-element-from-cache.d.ts.map +1 -0
  212. package/dist/typescript/get-element-from-cache.js +20 -0
  213. package/dist/typescript/get-element-from-cache.js.map +1 -0
  214. package/dist/typescript/get-frame-window.d.ts +2 -0
  215. package/dist/typescript/get-frame-window.d.ts.map +1 -0
  216. package/dist/typescript/get-frame-window.js +22 -0
  217. package/dist/typescript/get-frame-window.js.map +1 -0
  218. package/dist/typescript/get-local-storage-item.d.ts +3 -0
  219. package/dist/typescript/get-local-storage-item.d.ts.map +1 -0
  220. package/dist/typescript/get-local-storage-item.js +25 -0
  221. package/dist/typescript/get-local-storage-item.js.map +1 -0
  222. package/dist/typescript/get-local-storage-key.d.ts +3 -0
  223. package/dist/typescript/get-local-storage-key.d.ts.map +1 -0
  224. package/dist/typescript/get-local-storage-key.js +26 -0
  225. package/dist/typescript/get-local-storage-key.js.map +1 -0
  226. package/dist/typescript/get-local-storage-keys.d.ts +3 -0
  227. package/dist/typescript/get-local-storage-keys.d.ts.map +1 -0
  228. package/dist/typescript/get-local-storage-keys.js +25 -0
  229. package/dist/typescript/get-local-storage-keys.js.map +1 -0
  230. package/dist/typescript/get-local-storage-size.d.ts +3 -0
  231. package/dist/typescript/get-local-storage-size.d.ts.map +1 -0
  232. package/dist/typescript/get-local-storage-size.js +25 -0
  233. package/dist/typescript/get-local-storage-size.js.map +1 -0
  234. package/dist/typescript/get-location.d.ts +9 -0
  235. package/dist/typescript/get-location.d.ts.map +1 -0
  236. package/dist/typescript/get-location.js +49 -0
  237. package/dist/typescript/get-location.js.map +1 -0
  238. package/dist/typescript/get-session-storage-item.d.ts +3 -0
  239. package/dist/typescript/get-session-storage-item.d.ts.map +1 -0
  240. package/dist/typescript/get-session-storage-item.js +25 -0
  241. package/dist/typescript/get-session-storage-item.js.map +1 -0
  242. package/dist/typescript/get-session-storage-key.d.ts +3 -0
  243. package/dist/typescript/get-session-storage-key.d.ts.map +1 -0
  244. package/dist/typescript/get-session-storage-key.js +26 -0
  245. package/dist/typescript/get-session-storage-key.js.map +1 -0
  246. package/dist/typescript/get-session-storage-keys.d.ts +3 -0
  247. package/dist/typescript/get-session-storage-keys.d.ts.map +1 -0
  248. package/dist/typescript/get-session-storage-keys.js +25 -0
  249. package/dist/typescript/get-session-storage-keys.js.map +1 -0
  250. package/dist/typescript/get-session-storage-size.d.ts +3 -0
  251. package/dist/typescript/get-session-storage-size.d.ts.map +1 -0
  252. package/dist/typescript/get-session-storage-size.js +25 -0
  253. package/dist/typescript/get-session-storage-size.js.map +1 -0
  254. package/dist/typescript/get-size.d.ts +7 -0
  255. package/dist/typescript/get-size.d.ts.map +1 -0
  256. package/dist/typescript/get-size.js +36 -0
  257. package/dist/typescript/get-size.js.map +1 -0
  258. package/dist/typescript/get-text.d.ts +3 -0
  259. package/dist/typescript/get-text.d.ts.map +1 -0
  260. package/dist/typescript/get-text.js +294 -0
  261. package/dist/typescript/get-text.js.map +1 -0
  262. package/dist/typescript/get-top-left-coordinates.d.ts +4 -0
  263. package/dist/typescript/get-top-left-coordinates.d.ts.map +1 -0
  264. package/dist/typescript/get-top-left-coordinates.js +36 -0
  265. package/dist/typescript/get-top-left-coordinates.js.map +1 -0
  266. package/dist/typescript/is-displayed.d.ts +1 -2
  267. package/dist/typescript/is-displayed.d.ts.map +1 -1
  268. package/dist/typescript/is-displayed.js +3 -396
  269. package/dist/typescript/is-displayed.js.map +1 -1
  270. package/dist/typescript/is-editable.d.ts +2 -0
  271. package/dist/typescript/is-editable.d.ts.map +1 -0
  272. package/dist/typescript/is-editable.js +18 -0
  273. package/dist/typescript/is-editable.js.map +1 -0
  274. package/dist/typescript/is-enabled.d.ts +2 -0
  275. package/dist/typescript/is-enabled.d.ts.map +1 -0
  276. package/dist/typescript/is-enabled.js +18 -0
  277. package/dist/typescript/is-enabled.js.map +1 -0
  278. package/dist/typescript/is-focusable.d.ts +2 -0
  279. package/dist/typescript/is-focusable.d.ts.map +1 -0
  280. package/dist/typescript/is-focusable.js +20 -0
  281. package/dist/typescript/is-focusable.js.map +1 -0
  282. package/dist/typescript/is-interactable.d.ts +2 -0
  283. package/dist/typescript/is-interactable.d.ts.map +1 -0
  284. package/dist/typescript/is-interactable.js +19 -0
  285. package/dist/typescript/is-interactable.js.map +1 -0
  286. package/dist/typescript/is-selected.d.ts +3 -0
  287. package/dist/typescript/is-selected.d.ts.map +1 -0
  288. package/dist/typescript/is-selected.js +29 -0
  289. package/dist/typescript/is-selected.js.map +1 -0
  290. package/dist/typescript/remove-local-storage-item.d.ts +3 -0
  291. package/dist/typescript/remove-local-storage-item.d.ts.map +1 -0
  292. package/dist/typescript/remove-local-storage-item.js +25 -0
  293. package/dist/typescript/remove-local-storage-item.js.map +1 -0
  294. package/dist/typescript/remove-session-storage-item.d.ts +3 -0
  295. package/dist/typescript/remove-session-storage-item.d.ts.map +1 -0
  296. package/dist/typescript/remove-session-storage-item.js +25 -0
  297. package/dist/typescript/remove-session-storage-item.js.map +1 -0
  298. package/dist/typescript/set-local-storage-item.d.ts +3 -0
  299. package/dist/typescript/set-local-storage-item.d.ts.map +1 -0
  300. package/dist/typescript/set-local-storage-item.js +26 -0
  301. package/dist/typescript/set-local-storage-item.js.map +1 -0
  302. package/dist/typescript/set-session-storage-item.d.ts +3 -0
  303. package/dist/typescript/set-session-storage-item.d.ts.map +1 -0
  304. package/dist/typescript/set-session-storage-item.js +26 -0
  305. package/dist/typescript/set-session-storage-item.js.map +1 -0
  306. package/dist/typescript/submit.d.ts +3 -0
  307. package/dist/typescript/submit.d.ts.map +1 -0
  308. package/dist/typescript/submit.js +50 -0
  309. package/dist/typescript/submit.js.map +1 -0
  310. package/dist/typescript/type.d.ts +3 -0
  311. package/dist/typescript/type.d.ts.map +1 -0
  312. package/dist/typescript/type.js +201 -0
  313. package/dist/typescript/type.js.map +1 -0
  314. package/index.ts +44 -0
  315. package/package.json +306 -5
  316. package/typescript/accessibility-snapshot-wire.ts +20 -0
  317. package/typescript/accessibility-snapshot.ts +21 -0
  318. package/typescript/active-element.ts +19 -0
  319. package/typescript/clear-local-storage.ts +27 -0
  320. package/typescript/clear-session-storage.ts +27 -0
  321. package/typescript/clear.ts +73 -0
  322. package/typescript/click.ts +55 -0
  323. package/typescript/core/accessibility/accname.ts +587 -0
  324. package/typescript/core/accessibility/context.ts +116 -0
  325. package/typescript/core/accessibility/hidden.ts +242 -0
  326. package/typescript/core/accessibility/roles.ts +410 -0
  327. package/typescript/core/accessibility/snapshot.ts +61 -0
  328. package/typescript/core/accessibility/states.ts +233 -0
  329. package/typescript/core/accessibility/tree.ts +306 -0
  330. package/typescript/core/accessibility/types.ts +52 -0
  331. package/typescript/core/accessibility/value.ts +89 -0
  332. package/typescript/core/accessibility/wire.ts +123 -0
  333. package/typescript/core/attribute.ts +68 -0
  334. package/typescript/core/color.ts +257 -0
  335. package/typescript/core/editable.ts +63 -0
  336. package/typescript/core/element.ts +110 -0
  337. package/typescript/core/enabled.ts +76 -0
  338. package/typescript/core/error.ts +41 -0
  339. package/typescript/core/events.ts +268 -0
  340. package/typescript/core/focus.ts +92 -0
  341. package/typescript/core/focusable.ts +38 -0
  342. package/typescript/core/form.ts +81 -0
  343. package/typescript/core/frame.ts +105 -0
  344. package/typescript/core/geometry.ts +183 -0
  345. package/typescript/core/inject.ts +336 -0
  346. package/typescript/core/interactable.ts +30 -0
  347. package/typescript/core/keyboard.ts +369 -0
  348. package/typescript/core/keys.ts +204 -0
  349. package/typescript/core/locators.ts +704 -0
  350. package/typescript/core/mouse.ts +211 -0
  351. package/typescript/core/overflow.ts +172 -0
  352. package/typescript/core/scroll.ts +92 -0
  353. package/typescript/core/shown.ts +233 -0
  354. package/typescript/core/storage.ts +111 -0
  355. package/typescript/core/style.ts +32 -0
  356. package/typescript/core/useragent.ts +33 -0
  357. package/typescript/default-content.ts +20 -0
  358. package/typescript/execute-async-script.ts +20 -0
  359. package/typescript/execute-script.ts +20 -0
  360. package/typescript/find-element-fragment.ts +45 -0
  361. package/typescript/find-element.ts +18 -0
  362. package/typescript/find-elements.ts +1 -326
  363. package/typescript/frame-by-id-or-name.ts +22 -0
  364. package/typescript/frame-by-index.ts +19 -0
  365. package/typescript/get-attribute-value.ts +22 -0
  366. package/typescript/get-effective-style.ts +93 -0
  367. package/typescript/get-element-from-cache.ts +20 -0
  368. package/typescript/get-frame-window.ts +22 -0
  369. package/typescript/get-local-storage-item.ts +27 -0
  370. package/typescript/get-local-storage-key.ts +28 -0
  371. package/typescript/get-local-storage-keys.ts +27 -0
  372. package/typescript/get-local-storage-size.ts +27 -0
  373. package/typescript/get-location.ts +63 -0
  374. package/typescript/get-session-storage-item.ts +27 -0
  375. package/typescript/get-session-storage-key.ts +28 -0
  376. package/typescript/get-session-storage-keys.ts +27 -0
  377. package/typescript/get-session-storage-size.ts +27 -0
  378. package/typescript/get-size.ts +43 -0
  379. package/typescript/get-text.ts +353 -0
  380. package/typescript/get-top-left-coordinates.ts +38 -0
  381. package/typescript/is-displayed.ts +3 -498
  382. package/typescript/is-editable.ts +18 -0
  383. package/typescript/is-enabled.ts +18 -0
  384. package/typescript/is-focusable.ts +20 -0
  385. package/typescript/is-interactable.ts +19 -0
  386. package/typescript/is-selected.ts +31 -0
  387. package/typescript/remove-local-storage-item.ts +27 -0
  388. package/typescript/remove-session-storage-item.ts +27 -0
  389. package/typescript/set-local-storage-item.ts +28 -0
  390. package/typescript/set-session-storage-item.ts +28 -0
  391. package/typescript/submit.ts +53 -0
  392. package/typescript/type.ts +210 -0
@@ -0,0 +1,704 @@
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
+ // Shared locator strategy implementations for findElements (many) and
19
+ // findElement (single). Both atom entry points import from here so validation
20
+ // logic — especially what counts as an invalid selector — stays in one place
21
+ // and cannot drift between them.
22
+
23
+ import { botError, INVALID_ARGUMENT, INVALID_SELECTOR, NO_SUCH_ELEMENT } from './error.js'
24
+ import getVisibleText from '../get-text.js'
25
+
26
+ type LocatorTarget = Record<string, unknown>
27
+ type Root = Document | Element | ShadowRoot
28
+ type Rect = { left: number; top: number; width: number; height: number }
29
+ type RelativeFilter = { kind: string; args: unknown[] }
30
+
31
+ // ── shared helpers ─────────────────────────────────────────────────────────────
32
+
33
+ // Escapes characters with special meaning in CSS selector identifiers so an
34
+ // arbitrary string can be embedded in a CSS selector expression.
35
+ // locators/id.js:113-116 – cssEscape_ function.
36
+ function cssEscapeId(s: string): string {
37
+ return s.replace(/[\s'"\\#.:;,!?+<>=~*^$|%&@`{}\-/\[\]()]/g, (c) => '\\' + c)
38
+ }
39
+
40
+ function hasCssEscape(): boolean {
41
+ return typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
42
+ }
43
+
44
+ // Builds a CSS selector matching an exact id, or returns null when the value
45
+ // cannot be expressed as one and the caller must scan attributes instead.
46
+ // CSS.escape handles newlines, whitespace and leading digits; without it, the
47
+ // legacy escaping cannot handle a leading digit. A NUL can never be matched by
48
+ // a selector, because CSS replaces it with U+FFFD.
49
+ function idSelector(target: string): string | null {
50
+ if (target.indexOf('\0') !== -1) {
51
+ return null
52
+ }
53
+ if (hasCssEscape()) {
54
+ return '#' + CSS.escape(target)
55
+ }
56
+ return /^\d/.test(target) ? null : '#' + cssEscapeId(target)
57
+ }
58
+
59
+ // Builds a CSS selector matching one class. The Closure locator escaped only
60
+ // dots, so a class such as "a#b" was read as a class plus an id.
61
+ function classSelector(target: string): string {
62
+ return '.' + (hasCssEscape() ? CSS.escape(target) : cssEscapeId(target))
63
+ }
64
+
65
+ // Builds a CSS selector matching an exact name attribute, or returns null when
66
+ // the caller must scan attributes instead. Without CSS.escape, a line break
67
+ // cannot be written inside a quoted CSS string.
68
+ function nameSelector(target: string): string | null {
69
+ if (target.indexOf('\0') !== -1) {
70
+ return null
71
+ }
72
+ if (hasCssEscape()) {
73
+ return '[name="' + CSS.escape(target) + '"]'
74
+ }
75
+ if (/[\r\n\f]/.test(target)) {
76
+ return null
77
+ }
78
+ return '[name="' + target.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"]'
79
+ }
80
+
81
+ // Runs a selector built by idSelector or nameSelector, falling back to an
82
+ // exact attribute comparison when there is no selector or it is rejected.
83
+ // locators/name.js:34-41 – Closure compared getAttribute(name) directly.
84
+ function attributeMany(selector: string | null, attr: string, target: string, root: Root): Element[] {
85
+ if (selector !== null) {
86
+ try {
87
+ return Array.from(root.querySelectorAll(selector))
88
+ } catch (_e) {
89
+ // Fall through to the attribute scan.
90
+ }
91
+ }
92
+ return Array.from(root.querySelectorAll('*')).filter(el => el.getAttribute(attr) === target)
93
+ }
94
+
95
+ function attributeSingle(selector: string | null, attr: string, target: string, root: Root): Element | null {
96
+ if (selector !== null) {
97
+ try {
98
+ return root.querySelector(selector) ?? null
99
+ } catch (_e) {
100
+ // Fall through to the attribute scan.
101
+ }
102
+ }
103
+ return Array.from(root.querySelectorAll('*')).find(el => el.getAttribute(attr) === target) ?? null
104
+ }
105
+
106
+ // Maps non-breaking spaces to ordinary spaces, as bot.dom.getVisibleText did,
107
+ // so a link rendered as "A&nbsp;B" matches "A B".
108
+ function normalizeLinkText(s: string): string {
109
+ return s.replace(/\u00a0/g, ' ')
110
+ }
111
+
112
+ // Reads the visible text of a link element, trimming surrounding whitespace.
113
+ // locators/link_text.js:51-58 – getVisibleText + trim pattern.
114
+ // innerText is not used because it falls back to textContent for elements that
115
+ // are not rendered, which would let hidden links match.
116
+ function getLinkText(el: Element): string {
117
+ return getVisibleText(el).replace(/^[\s]+|[\s]+$/g, '')
118
+ }
119
+
120
+ // ── many (multi-element) implementations ──────────────────────────────────────
121
+
122
+ function classNameMany(target: string, root: Root): Element[] {
123
+ if (!target) {
124
+ throw botError(INVALID_SELECTOR, 'No class name specified')
125
+ }
126
+ target = target.trim()
127
+ if (target.indexOf(' ') !== -1) {
128
+ throw botError(INVALID_SELECTOR, 'Compound class names not permitted')
129
+ }
130
+ try {
131
+ return Array.from(root.querySelectorAll(classSelector(target)))
132
+ } catch (_e) {
133
+ throw botError(INVALID_SELECTOR, 'An invalid or illegal class name was specified')
134
+ }
135
+ }
136
+
137
+ function cssMany(target: string, root: Root): Element[] {
138
+ try {
139
+ return Array.from(root.querySelectorAll(target))
140
+ } catch (_e) {
141
+ throw botError(INVALID_SELECTOR, 'An invalid or illegal CSS selector was specified: ' + target)
142
+ }
143
+ }
144
+
145
+ function idMany(target: string, root: Root): Element[] {
146
+ if (!target) {
147
+ return []
148
+ }
149
+ return attributeMany(idSelector(target), 'id', target, root)
150
+ }
151
+
152
+ function linkTextMany(target: string, root: Root, partial: boolean): Element[] {
153
+ target = normalizeLinkText(target)
154
+ return Array.from(root.querySelectorAll('a')).filter(el => {
155
+ const text = getLinkText(el)
156
+ return partial ? text.indexOf(target) !== -1 : text === target
157
+ })
158
+ }
159
+
160
+ function nameMany(target: string, root: Root): Element[] {
161
+ return attributeMany(nameSelector(target), 'name', target, root)
162
+ }
163
+
164
+ function tagNameMany(target: string, root: Root): Element[] {
165
+ if (target === '') {
166
+ throw botError(INVALID_SELECTOR, 'Unable to locate an element with the tagName ""')
167
+ }
168
+ // ShadowRoot does not implement getElementsByTagName; fall through to the
169
+ // querySelectorAll path in that case.
170
+ if ('getElementsByTagName' in root) {
171
+ return Array.from((root as Document | Element).getElementsByTagName(target))
172
+ }
173
+ const elements = Array.from(root.querySelectorAll('*'))
174
+ if (target === '*') {
175
+ return elements
176
+ }
177
+ // XHTML elements compare against localName using the folded (lowercase) form;
178
+ // non-XHTML (e.g. SVG in a shadow root) compare case-sensitively.
179
+ const html = 'http://www.w3.org/1999/xhtml'
180
+ const folded = target.toLowerCase()
181
+ return elements.filter(el =>
182
+ el.namespaceURI === html ? el.localName === folded : el.localName === target)
183
+ }
184
+
185
+ // Shared XPath namespace resolver constants.
186
+ const DEFAULT_NS_RESOLVER = (function () {
187
+ const ns: Record<string, string> = { svg: 'http://www.w3.org/2000/svg' }
188
+ return (prefix: string): string | null => ns[prefix] || null
189
+ })()
190
+
191
+ const ORDERED_NODE_SNAPSHOT_TYPE = 7
192
+ // XPathResult.FIRST_ORDERED_NODE_TYPE: asks the engine to stop at the first
193
+ // match, which is more efficient than a full snapshot for single-element use.
194
+ const FIRST_ORDERED_NODE_TYPE = 9
195
+
196
+ // Build a namespace-aware resolver for XPath expressions containing a colon.
197
+ // When the expression has no colon the expensive DOM scan is skipped entirely.
198
+ // locators/xpath.js:99-135 – evaluate_ namespace handling, minus IE6 path.
199
+ function buildNsResolver(
200
+ target: string,
201
+ doc: Document,
202
+ ): ((prefix: string | null) => string | null) | null {
203
+ if (target.indexOf(':') === -1) {
204
+ return null
205
+ }
206
+ const reversedNs: Record<string, string> = {}
207
+ const allNodes = doc.getElementsByTagName('*')
208
+ for (let i = 0; i < allNodes.length; i++) {
209
+ const n = allNodes[i]
210
+ const ns = n.namespaceURI
211
+ if (ns && !reversedNs[ns]) {
212
+ let prefix = n.lookupPrefix(ns)
213
+ if (!prefix) {
214
+ const m = ns.match('.*/(\\w+)/?$')
215
+ prefix = m ? m[1] : 'xhtml'
216
+ }
217
+ reversedNs[ns] = prefix!
218
+ }
219
+ }
220
+ const namespaces: Record<string, string> = {}
221
+ for (const key in reversedNs) {
222
+ namespaces[reversedNs[key]] = key
223
+ }
224
+ return (prefix: string | null): string | null => namespaces[prefix || ''] || null
225
+ }
226
+
227
+ function xpathMany(target: string, root: Root): Element[] {
228
+ const doc = (root as Document).documentElement
229
+ ? (root as Document)
230
+ : root.ownerDocument!
231
+ if (!doc.documentElement) {
232
+ return []
233
+ }
234
+ try {
235
+ const resolver = buildNsResolver(target, doc)
236
+ let result: XPathResult | null = null
237
+ try {
238
+ result = doc.evaluate(target, root, resolver, ORDERED_NODE_SNAPSHOT_TYPE, null)
239
+ } catch (te) {
240
+ if ((te as Error).name === 'TypeError') {
241
+ // Some environments reject a null resolver even when one is not needed;
242
+ // fall back to the document's own NS resolver.
243
+ const fallback = doc.createNSResolver
244
+ ? doc.createNSResolver(doc.documentElement!)
245
+ : DEFAULT_NS_RESOLVER
246
+ result = doc.evaluate(target, root, fallback, ORDERED_NODE_SNAPSHOT_TYPE, null)
247
+ } else {
248
+ throw te
249
+ }
250
+ }
251
+
252
+ if (!result) {
253
+ return []
254
+ }
255
+
256
+ const results: Element[] = []
257
+ for (let i = 0; i < result.snapshotLength; i++) {
258
+ const node = result.snapshotItem(i)
259
+ if (!node || node.nodeType !== Node.ELEMENT_NODE) {
260
+ throw botError(
261
+ INVALID_SELECTOR,
262
+ 'The result of the xpath expression "' + target + '" is: ' + node + '. It should be an element.',
263
+ )
264
+ }
265
+ results.push(node as Element)
266
+ }
267
+ return results
268
+ } catch (ex) {
269
+ // Firefox throws NS_ERROR_ILLEGAL_VALUE while a page is mid-reload;
270
+ // treat it as an empty result rather than an error.
271
+ // locators/xpath.js:155-158 – Gecko-specific reload exception.
272
+ if ((ex as Error & { name?: string }).name === 'NS_ERROR_ILLEGAL_VALUE') {
273
+ return []
274
+ }
275
+ if ((ex as Error & { code?: string }).code === INVALID_SELECTOR) {
276
+ throw ex
277
+ }
278
+ throw botError(
279
+ INVALID_SELECTOR,
280
+ 'Unable to locate an element with the xpath expression ' + target +
281
+ ' because of the following error:\n' + ex,
282
+ )
283
+ }
284
+ }
285
+
286
+ // ── single (first-match) implementations ──────────────────────────────────────
287
+ //
288
+ // These are NOT simply "many()[0]". Each strategy has a dedicated single
289
+ // implementation because:
290
+ // - xpath.single uses FIRST_ORDERED_NODE_TYPE (9) not ORDERED_NODE_SNAPSHOT_TYPE (7),
291
+ // which lets the XPath engine short-circuit after the first match.
292
+ // - css.single explicitly throws INVALID_SELECTOR for an empty selector
293
+ // (locators/css.js:48-51) rather than catching the querySelectorAll error.
294
+ // - id.single scopes containment via querySelector on the root, faithfully
295
+ // reproducing the Closure getElementById + goog.dom.contains guard
296
+ // (locators/id.js:48-68) without the IE name/id confusion branch (dropped:
297
+ // IE is no longer a supported browser).
298
+ // - relative.single delegates to relativeMany; root is passed through.
299
+
300
+ function classNameSingle(target: string, root: Root): Element | null {
301
+ if (!target) {
302
+ throw botError(INVALID_SELECTOR, 'No class name specified')
303
+ }
304
+ target = target.trim()
305
+ if (target.indexOf(' ') !== -1) {
306
+ throw botError(INVALID_SELECTOR, 'Compound class names not permitted')
307
+ }
308
+ try {
309
+ return root.querySelector(classSelector(target)) ?? null
310
+ } catch (_e) {
311
+ throw botError(INVALID_SELECTOR, 'An invalid or illegal class name was specified')
312
+ }
313
+ }
314
+
315
+ function cssSingle(target: string, root: Root): Element | null {
316
+ // locators/css.js:48-51 – explicitly rejects an empty selector before
317
+ // reaching querySelector, matching Closure's distinct INVALID_SELECTOR throw.
318
+ if (!target || !target.trim()) {
319
+ throw botError(INVALID_SELECTOR, 'No selector specified')
320
+ }
321
+ try {
322
+ return root.querySelector(target) ?? null
323
+ } catch (_e) {
324
+ throw botError(INVALID_SELECTOR, 'An invalid or illegal CSS selector was specified: ' + target)
325
+ }
326
+ }
327
+
328
+ function idSingle(target: string, root: Root): Element | null {
329
+ if (!target) {
330
+ return null
331
+ }
332
+ // locators/id.js:48-68 – Closure getElementById + containment check.
333
+ // Using querySelector scoped to root achieves the same containment guarantee
334
+ // without needing document.getElementById: only descendants of root are
335
+ // returned, so an element elsewhere in the page is automatically excluded,
336
+ // and root itself is never included (querySelector only looks at descendants).
337
+ // Dropped: the IE name/id confusion branch that needed getAttribute('id')
338
+ // re-validation — IE is no longer supported.
339
+ return attributeSingle(idSelector(target), 'id', target, root)
340
+ }
341
+
342
+ function linkTextSingle(target: string, root: Root, partial: boolean): Element | null {
343
+ // locators/link_text.js:40-61 – single_ iterates anchors and returns first match.
344
+ target = normalizeLinkText(target)
345
+ const anchors = Array.from(root.querySelectorAll('a'))
346
+ const found = anchors.find(el => {
347
+ const text = getLinkText(el)
348
+ return partial ? text.indexOf(target) !== -1 : text === target
349
+ })
350
+ return found ?? null
351
+ }
352
+
353
+ function nameSingle(target: string, root: Root): Element | null {
354
+ // locators/name.js:34-41 – scans elements and returns the first name match.
355
+ return attributeSingle(nameSelector(target), 'name', target, root)
356
+ }
357
+
358
+ function tagNameSingle(target: string, root: Root): Element | null {
359
+ if (target === '') {
360
+ throw botError(INVALID_SELECTOR, 'Unable to locate an element with the tagName ""')
361
+ }
362
+ // locators/tag_name.js:32-38 – getElementsByTagName()[0] || null.
363
+ // ShadowRoot lacks getElementsByTagName; use the same querySelectorAll +
364
+ // localName fallback that tagNameMany uses.
365
+ if ('getElementsByTagName' in root) {
366
+ return (root as Document | Element).getElementsByTagName(target)[0] ?? null
367
+ }
368
+ const elements = Array.from(root.querySelectorAll('*'))
369
+ if (target === '*') {
370
+ return elements[0] ?? null
371
+ }
372
+ const html = 'http://www.w3.org/1999/xhtml'
373
+ const folded = target.toLowerCase()
374
+ const found = elements.find(el =>
375
+ el.namespaceURI === html ? el.localName === folded : el.localName === target)
376
+ return found ?? null
377
+ }
378
+
379
+ function xpathSingle(target: string, root: Root): Element | null {
380
+ const doc = (root as Document).documentElement
381
+ ? (root as Document)
382
+ : root.ownerDocument!
383
+ if (!doc.documentElement) {
384
+ return null
385
+ }
386
+ try {
387
+ const resolver = buildNsResolver(target, doc)
388
+ let result: XPathResult | null = null
389
+ // locators/xpath.js:187-211 – single uses FIRST_ORDERED_NODE_TYPE (9) so the
390
+ // XPath engine short-circuits after the first match. The many variant uses
391
+ // ORDERED_NODE_SNAPSHOT_TYPE (7); these are genuinely different XPath result
392
+ // types and are not interchangeable.
393
+ try {
394
+ result = doc.evaluate(target, root, resolver, FIRST_ORDERED_NODE_TYPE, null)
395
+ } catch (te) {
396
+ if ((te as Error).name === 'TypeError') {
397
+ const fallback = doc.createNSResolver
398
+ ? doc.createNSResolver(doc.documentElement!)
399
+ : DEFAULT_NS_RESOLVER
400
+ result = doc.evaluate(target, root, fallback, FIRST_ORDERED_NODE_TYPE, null)
401
+ } else {
402
+ throw te
403
+ }
404
+ }
405
+
406
+ if (!result) return null
407
+ const node = result.singleNodeValue
408
+ if (node === null) return null
409
+ if (!node || node.nodeType !== Node.ELEMENT_NODE) {
410
+ throw botError(
411
+ INVALID_SELECTOR,
412
+ 'The result of the xpath expression "' + target + '" is: ' + node + '. It should be an element.',
413
+ )
414
+ }
415
+ return node as Element
416
+ } catch (ex) {
417
+ if ((ex as Error & { name?: string }).name === 'NS_ERROR_ILLEGAL_VALUE') {
418
+ return null
419
+ }
420
+ if ((ex as Error & { code?: string }).code === INVALID_SELECTOR) {
421
+ throw ex
422
+ }
423
+ throw botError(
424
+ INVALID_SELECTOR,
425
+ 'Unable to locate an element with the xpath expression ' + target +
426
+ ' because of the following error:\n' + ex,
427
+ )
428
+ }
429
+ }
430
+
431
+ // ── relative locator internals ─────────────────────────────────────────────────
432
+
433
+ function getClientRect(element: Element): Rect {
434
+ const r = element.getBoundingClientRect()
435
+ return { left: r.left, top: r.top, width: r.width, height: r.height }
436
+ }
437
+
438
+ // Resolves a selector argument inside a relative locator filter to a single
439
+ // Element. outerRoot is the root passed to findElements / findElement by the
440
+ // caller; anchors are searched inside it first, then in the full document.
441
+ // locators/relative.js:263-286 – resolve_.
442
+ function resolveAnchor(selector: unknown, outerRoot: Root | undefined): Element {
443
+ if (selector instanceof Element) {
444
+ return selector
445
+ }
446
+ if (typeof selector === 'function') {
447
+ return resolveAnchor((selector as () => unknown)(), outerRoot)
448
+ }
449
+ if (selector && typeof selector === 'object') {
450
+ // Prefer an anchor inside outerRoot before falling back to the document.
451
+ // Closure searched the document first; searching the root first is
452
+ // deliberate, because a document search cannot reach into a shadow root.
453
+ // When a locator matches anchors both inside and outside the root, the
454
+ // inner one wins (pinned in find_elements_typescript_test.html).
455
+ let found = outerRoot ? findElements(selector as LocatorTarget, outerRoot) : []
456
+ if (!found.length) {
457
+ found = findElements(selector as LocatorTarget)
458
+ }
459
+ if (!found.length) {
460
+ throw botError(NO_SUCH_ELEMENT, 'No element has been found by ' + JSON.stringify(selector))
461
+ }
462
+ return found[0]
463
+ }
464
+ throw botError(INVALID_ARGUMENT, 'Selector is of wrong type: ' + JSON.stringify(selector))
465
+ }
466
+
467
+ function makeProximityFilter(
468
+ selector: unknown,
469
+ outerRoot: Root | undefined,
470
+ test: (anchor: Rect, candidate: Rect) => boolean,
471
+ ): (candidate: Element) => boolean {
472
+ return (candidate) => test(getClientRect(resolveAnchor(selector, outerRoot)), getClientRect(candidate))
473
+ }
474
+
475
+ function sortByProximity(anchor: Element, elements: Element[]): Element[] {
476
+ const ar = getClientRect(anchor)
477
+ const acx = ar.left + Math.max(1, ar.width) / 2
478
+ const acy = ar.top + Math.max(1, ar.height) / 2
479
+ return elements.slice().sort((a, b) => {
480
+ const ra = getClientRect(a)
481
+ const rb = getClientRect(b)
482
+ const da = Math.sqrt(
483
+ Math.pow(acx - (ra.left + Math.max(1, ra.width) / 2), 2) +
484
+ Math.pow(acy - (ra.top + Math.max(1, ra.height) / 2), 2),
485
+ )
486
+ const db = Math.sqrt(
487
+ Math.pow(acx - (rb.left + Math.max(1, rb.width) / 2), 2) +
488
+ Math.pow(acy - (rb.top + Math.max(1, rb.height) / 2), 2),
489
+ )
490
+ return da - db
491
+ })
492
+ }
493
+
494
+ // relativeMany is used by both findElements and findElement. The root argument
495
+ // is ignored for the spatial filters themselves (they operate on page layout),
496
+ // but is passed when searching for the "root" element pool.
497
+ // locators/relative.js:434-459 – many; locators/relative.js:418-424 – single.
498
+ //
499
+ // outerRoot is the root originally supplied to findElements/findElement;
500
+ // it threads into resolveAnchor so that shadow-root anchors can be found.
501
+ function relativeMany(
502
+ target: Record<string, unknown>,
503
+ actualRoot: Root,
504
+ outerRoot: Root | undefined,
505
+ ): Element[] {
506
+ if (
507
+ !Object.prototype.hasOwnProperty.call(target, 'root') ||
508
+ !Object.prototype.hasOwnProperty.call(target, 'filters')
509
+ ) {
510
+ throw botError(
511
+ INVALID_ARGUMENT,
512
+ 'Locator not suitable for relative locators: ' + JSON.stringify(target),
513
+ )
514
+ }
515
+ const filters = target['filters']
516
+ if (!Array.isArray(filters)) {
517
+ throw botError(INVALID_ARGUMENT, 'Targets should be an array: ' + JSON.stringify(target))
518
+ }
519
+
520
+ let elements: Element[]
521
+ const rootTarget = target['root']
522
+ if (rootTarget instanceof Element) {
523
+ elements = [rootTarget]
524
+ } else {
525
+ elements = findElements(rootTarget as LocatorTarget, actualRoot)
526
+ }
527
+
528
+ if (!elements.length) {
529
+ return []
530
+ }
531
+
532
+ // Build the strategy map here so outerRoot is captured in the closures.
533
+ const RELATIVE_STRATEGIES: Record<string, (...args: unknown[]) => (el: Element) => boolean> = {
534
+ above: (sel) =>
535
+ makeProximityFilter(sel, outerRoot, (a, c) => c.top + c.height <= a.top),
536
+ below: (sel) =>
537
+ makeProximityFilter(sel, outerRoot, (a, c) => c.top >= a.top + a.height),
538
+ left: (sel) =>
539
+ makeProximityFilter(sel, outerRoot, (a, c) => c.left + c.width <= a.left),
540
+ right: (sel) =>
541
+ makeProximityFilter(sel, outerRoot, (a, c) => c.left >= a.left + a.width),
542
+ near: (sel, distArg) => {
543
+ const distFromSelector =
544
+ typeof (sel as Record<string, unknown>)['distance'] === 'number'
545
+ ? ((sel as Record<string, unknown>)['distance'] as number)
546
+ : 0
547
+ const distance =
548
+ typeof distArg === 'number' && distArg > 0 ? distArg : distFromSelector || 50
549
+ return (candidate: Element): boolean => {
550
+ const anchor = resolveAnchor(sel, outerRoot)
551
+ if (anchor === candidate) return false
552
+ const a = getClientRect(anchor)
553
+ const c = getClientRect(candidate)
554
+ const expanded = {
555
+ left: a.left - distance,
556
+ top: a.top - distance,
557
+ width: a.width + distance * 2,
558
+ height: a.height + distance * 2,
559
+ }
560
+ return (
561
+ c.left < expanded.left + expanded.width &&
562
+ c.left + c.width > expanded.left &&
563
+ c.top < expanded.top + expanded.height &&
564
+ c.top + c.height > expanded.top
565
+ )
566
+ }
567
+ },
568
+ straightAbove: (sel) =>
569
+ makeProximityFilter(
570
+ sel,
571
+ outerRoot,
572
+ (a, c) => c.left < a.left + a.width && c.left + c.width > a.left && c.top + c.height <= a.top,
573
+ ),
574
+ straightBelow: (sel) =>
575
+ makeProximityFilter(
576
+ sel,
577
+ outerRoot,
578
+ (a, c) => c.left < a.left + a.width && c.left + c.width > a.left && c.top >= a.top + a.height,
579
+ ),
580
+ straightLeft: (sel) =>
581
+ makeProximityFilter(
582
+ sel,
583
+ outerRoot,
584
+ (a, c) => c.top < a.top + a.height && c.top + c.height > a.top && c.left + c.width <= a.left,
585
+ ),
586
+ straightRight: (sel) =>
587
+ makeProximityFilter(
588
+ sel,
589
+ outerRoot,
590
+ (a, c) => c.top < a.top + a.height && c.top + c.height > a.top && c.left >= a.left + a.width,
591
+ ),
592
+ }
593
+
594
+ const matched = elements.filter(el => {
595
+ if (!el) return false
596
+ return (filters as RelativeFilter[]).every(filter => {
597
+ const strategy = RELATIVE_STRATEGIES[filter.kind]
598
+ if (!strategy) {
599
+ throw botError(INVALID_ARGUMENT, 'Cannot find filter suitable for ' + filter.kind)
600
+ }
601
+ return strategy(...filter.args)(el)
602
+ })
603
+ })
604
+
605
+ const finalFilter = filters[filters.length - 1] as RelativeFilter | undefined
606
+ if (!finalFilter || !RELATIVE_STRATEGIES[finalFilter.kind]) {
607
+ return matched
608
+ }
609
+ const lastAnchor = resolveAnchor(finalFilter.args[0], outerRoot)
610
+ return sortByProximity(lastAnchor, matched)
611
+ }
612
+
613
+ // ── exported functions ─────────────────────────────────────────────────────────
614
+
615
+ // Finds all elements matching the given locator target, optionally scoped to a
616
+ // root. Returns an empty array when nothing matches. Throws for unsupported
617
+ // strategies. Ported from bot.locators.findElements (locators/locators.js:152).
618
+ export function findElements(target: LocatorTarget, root?: Root): Element[] {
619
+ const actualRoot: Root = root || document
620
+ const keys = Object.keys(target).filter(k => Object.prototype.hasOwnProperty.call(target, k))
621
+ if (!keys.length) {
622
+ throw botError(INVALID_ARGUMENT, 'Unsupported locator strategy: (empty)')
623
+ }
624
+ const key = keys[0]
625
+ const value = target[key]
626
+
627
+ switch (key) {
628
+ case 'className':
629
+ case 'class name':
630
+ return classNameMany(value as string, actualRoot)
631
+ case 'css':
632
+ case 'css selector':
633
+ return cssMany(value as string, actualRoot)
634
+ case 'id':
635
+ return idMany(value as string, actualRoot)
636
+ case 'linkText':
637
+ case 'link text':
638
+ return linkTextMany(value as string, actualRoot, false)
639
+ case 'partialLinkText':
640
+ case 'partial link text':
641
+ return linkTextMany(value as string, actualRoot, true)
642
+ case 'name':
643
+ return nameMany(value as string, actualRoot)
644
+ case 'tagName':
645
+ case 'tag name':
646
+ return tagNameMany(value as string, actualRoot)
647
+ case 'xpath':
648
+ return xpathMany(value as string, actualRoot)
649
+ case 'relative':
650
+ return relativeMany(value as Record<string, unknown>, actualRoot, root)
651
+ default:
652
+ throw botError(INVALID_ARGUMENT, 'Unsupported locator strategy: ' + key)
653
+ }
654
+ }
655
+
656
+ // Finds the first element matching the given locator target, optionally scoped
657
+ // to a root. Returns null when nothing matches — it does NOT throw for a
658
+ // no-match. Throws ONLY for an unsupported or invalid strategy key.
659
+ // Ported from bot.locators.findElement (locators/locators.js:124).
660
+ //
661
+ // This must NOT be implemented as findElements(...)[0]; each strategy has its
662
+ // own single-element implementation (most importantly, xpathSingle uses
663
+ // FIRST_ORDERED_NODE_TYPE which is more efficient and semantically distinct
664
+ // from the snapshot type used by xpathMany).
665
+ export function findElement(target: LocatorTarget, root?: Root): Element | null {
666
+ const actualRoot: Root = root || document
667
+ const keys = Object.keys(target).filter(k => Object.prototype.hasOwnProperty.call(target, k))
668
+ if (!keys.length) {
669
+ throw botError(INVALID_ARGUMENT, 'Unsupported locator strategy: (empty)')
670
+ }
671
+ const key = keys[0]
672
+ const value = target[key]
673
+
674
+ switch (key) {
675
+ case 'className':
676
+ case 'class name':
677
+ return classNameSingle(value as string, actualRoot)
678
+ case 'css':
679
+ case 'css selector':
680
+ return cssSingle(value as string, actualRoot)
681
+ case 'id':
682
+ return idSingle(value as string, actualRoot)
683
+ case 'linkText':
684
+ case 'link text':
685
+ return linkTextSingle(value as string, actualRoot, false)
686
+ case 'partialLinkText':
687
+ case 'partial link text':
688
+ return linkTextSingle(value as string, actualRoot, true)
689
+ case 'name':
690
+ return nameSingle(value as string, actualRoot)
691
+ case 'tagName':
692
+ case 'tag name':
693
+ return tagNameSingle(value as string, actualRoot)
694
+ case 'xpath':
695
+ return xpathSingle(value as string, actualRoot)
696
+ case 'relative':
697
+ // locators/relative.js:418-424 – relative.single delegates to many,
698
+ // returns first result or null. root passes through so anchor resolution
699
+ // can find shadow-root elements.
700
+ return relativeMany(value as Record<string, unknown>, actualRoot, root)[0] ?? null
701
+ default:
702
+ throw botError(INVALID_ARGUMENT, 'Unsupported locator strategy: ' + key)
703
+ }
704
+ }