@orkestrel/test 0.0.26 → 0.0.28
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.
- package/README.md +12 -7
- package/dist/src/browser/index.d.ts +937 -45
- package/dist/src/browser/index.js +3924 -2822
- package/dist/src/browser/index.js.map +1 -1
- package/dist/src/core/index.cjs +51 -0
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +60 -0
- package/dist/src/core/index.d.ts +60 -0
- package/dist/src/core/index.js +51 -1
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +71 -0
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +34 -0
- package/dist/src/server/index.d.ts +34 -0
- package/dist/src/server/index.js +72 -2
- package/dist/src/server/index.js.map +1 -1
- package/package.json +10 -4
|
@@ -23,11 +23,30 @@
|
|
|
23
23
|
* @packageDocumentation
|
|
24
24
|
*/
|
|
25
25
|
|
|
26
|
+
import type { ChoiceOptions } from '@orkestrel/test';
|
|
27
|
+
import type { FixtureFile } from '@orkestrel/test';
|
|
26
28
|
import type { JourneyVariant } from '@orkestrel/test';
|
|
27
29
|
import type { StatechartStatus } from '@orkestrel/test';
|
|
28
30
|
import type { StateScenario } from '@orkestrel/test';
|
|
29
31
|
import type { WaitOptions } from '@orkestrel/test';
|
|
30
32
|
|
|
33
|
+
/**
|
|
34
|
+
* Represents the accessibility node the browser computed for one element.
|
|
35
|
+
*
|
|
36
|
+
* @remarks
|
|
37
|
+
* The values are the browser's own computation, which is what separates this from the DOM-based
|
|
38
|
+
* `readRole`, `readName`, and `readStates` readings: the browser applies every naming and role rule
|
|
39
|
+
* itself, so the node is what an assistive technology is handed.
|
|
40
|
+
*/
|
|
41
|
+
export declare interface AccessibilityNode {
|
|
42
|
+
/** Holds the computed role, or `undefined` when the node states none. */
|
|
43
|
+
readonly role: string | undefined;
|
|
44
|
+
/** Holds the computed accessible name, or `undefined` when the node states none. */
|
|
45
|
+
readonly name: string | undefined;
|
|
46
|
+
/** Maps each property name to its value; an ID reference reads as the list of referenced IDs. */
|
|
47
|
+
readonly properties: Readonly<Record<string, unknown>>;
|
|
48
|
+
}
|
|
49
|
+
|
|
31
50
|
/**
|
|
32
51
|
* Names the interactive ARIA roles a bare accessible name is searched across.
|
|
33
52
|
*
|
|
@@ -38,6 +57,34 @@ import type { WaitOptions } from '@orkestrel/test';
|
|
|
38
57
|
*/
|
|
39
58
|
export declare const ACCESSIBLE_ROLES: readonly string[];
|
|
40
59
|
|
|
60
|
+
/**
|
|
61
|
+
* Adopts CSS text into the document with an idempotent release operation.
|
|
62
|
+
*
|
|
63
|
+
* @param text - The compiled sheet text.
|
|
64
|
+
* @returns The adopted sheet and its release operation.
|
|
65
|
+
*
|
|
66
|
+
* @example
|
|
67
|
+
* ```ts
|
|
68
|
+
* const adopted = adoptSheet('.sample { display: block }')
|
|
69
|
+
* adopted.release()
|
|
70
|
+
* ```
|
|
71
|
+
*/
|
|
72
|
+
export declare function adoptSheet(text: string): SheetAdoption;
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Represents the animations running on one element and its subtree, split by whether each one ends.
|
|
76
|
+
*
|
|
77
|
+
* @remarks
|
|
78
|
+
* An animation counts as endless when its effect declares infinite iterations. A paused, an idle,
|
|
79
|
+
* and a finished animation are at rest, so neither list holds one.
|
|
80
|
+
*/
|
|
81
|
+
export declare interface AnimationReading {
|
|
82
|
+
/** Lists the running animations that end, the ones `waitForAnimations` waits on. */
|
|
83
|
+
readonly finite: readonly Animation[];
|
|
84
|
+
/** Lists the running animations whose effect declares infinite iterations. */
|
|
85
|
+
readonly endless: readonly Animation[];
|
|
86
|
+
}
|
|
87
|
+
|
|
41
88
|
/**
|
|
42
89
|
* Composites one color over another.
|
|
43
90
|
*
|
|
@@ -371,6 +418,23 @@ export declare interface CensusReading {
|
|
|
371
418
|
readonly undeclared: readonly string[];
|
|
372
419
|
}
|
|
373
420
|
|
|
421
|
+
/**
|
|
422
|
+
* Activates a labeled native file input and fulfills its observed chooser with fixture bytes.
|
|
423
|
+
*
|
|
424
|
+
* @param name - The input's exact accessible label.
|
|
425
|
+
* @param files - The fixture selection; an empty collection clears the selection, not an OS Cancel gesture.
|
|
426
|
+
* @param options - The activation method and provider wait budget.
|
|
427
|
+
* @returns A promise resolving after the correct native chooser receives the fixture selection.
|
|
428
|
+
* @throws When the input is refused, the provider command is unregistered, or the expected chooser does not open.
|
|
429
|
+
* @remarks Register the server entry's `chooseFiles` function as the `chooseFiles` command in the workspace's
|
|
430
|
+
* `configs/commands.ts`, which the root configuration passes to every browser project.
|
|
431
|
+
* @example
|
|
432
|
+
* ```ts
|
|
433
|
+
* await chooseAccessible('Attachments', [{ name: 'note.txt', mime: 'text/plain', bytes: [72, 105] }])
|
|
434
|
+
* ```
|
|
435
|
+
*/
|
|
436
|
+
export declare function chooseAccessible(name: string, files: readonly FixtureFile[], options?: ChoiceOptions): Promise<void>;
|
|
437
|
+
|
|
374
438
|
/**
|
|
375
439
|
* Clears both browser storage surfaces.
|
|
376
440
|
*
|
|
@@ -480,6 +544,82 @@ export declare function clickDisclosure(name: string): Promise<void>;
|
|
|
480
544
|
*/
|
|
481
545
|
export declare function clipsOverflow(element: Element): boolean;
|
|
482
546
|
|
|
547
|
+
/**
|
|
548
|
+
* Collects the ancestors of an element that clip their descendants' overflow.
|
|
549
|
+
*
|
|
550
|
+
* @param element - The element whose ancestors to read.
|
|
551
|
+
* @returns Every ancestor element for which the {@link clipsOverflow} helper reports true, nearest
|
|
552
|
+
* first, and an empty list where the element has none.
|
|
553
|
+
* @throws Thrown when the element is not connected to a document, because a disconnected element
|
|
554
|
+
* resolves no style and its ancestors would all read as clipping.
|
|
555
|
+
*
|
|
556
|
+
* @remarks
|
|
557
|
+
* The walk climbs the flat tree, the tree a browser paints. A step goes to the slot an element is
|
|
558
|
+
* assigned to, else to its parent element, else to the host of the shadow root it stands in. So the
|
|
559
|
+
* wrapper around a slot clips the child assigned to that slot, a shadow tree's wrappers clip what
|
|
560
|
+
* stands in it and then what its host stands in, and the walk ends at the root element, which has
|
|
561
|
+
* none of the three. The `assignedSlot` property reports no slot of a closed shadow root, so a
|
|
562
|
+
* child assigned into one climbs through its light parent instead. The element itself is not one of
|
|
563
|
+
* its own ancestors. Each step returns its own parent's frame, if it is one, ahead of the frames
|
|
564
|
+
* above it, so the depth of the flat tree bounds the recursion.
|
|
565
|
+
*
|
|
566
|
+
* @example
|
|
567
|
+
* ```ts
|
|
568
|
+
* collectClippingAncestors(bar) // [frame] where a hidden-overflow frame wraps the bar
|
|
569
|
+
* ```
|
|
570
|
+
*/
|
|
571
|
+
export declare function collectClippingAncestors(element: Element): readonly Element[];
|
|
572
|
+
|
|
573
|
+
/**
|
|
574
|
+
* Collects the rendered boxes a person can scroll.
|
|
575
|
+
*
|
|
576
|
+
* @param root - The element whose subtree is searched, the root included.
|
|
577
|
+
* @param axis - The scroll axis to keep: `'inline'` for boxes that scroll across, `'block'` for
|
|
578
|
+
* boxes that scroll down. Omit it to keep both.
|
|
579
|
+
* @returns Each rendered element, in document order, whose resolved overflow scrolls on a searched
|
|
580
|
+
* axis where its content is larger than its box.
|
|
581
|
+
*
|
|
582
|
+
* @remarks
|
|
583
|
+
* A screenshot shows no scrollbar where the browser overlays them, so a frame alone never tells
|
|
584
|
+
* that a pane scrolls or how far. A box counts when its `overflow-x` or `overflow-y` value is the
|
|
585
|
+
* `auto` keyword or the `scroll` keyword and its content overflows on that axis; a `hidden` or
|
|
586
|
+
* `clip` box cuts its content without letting anyone scroll it, and a box whose content fits has
|
|
587
|
+
* nowhere to go. An element that {@link isRendered} reports false for is left out, because a person
|
|
588
|
+
* cannot scroll a box the page does not show.
|
|
589
|
+
*
|
|
590
|
+
* @example
|
|
591
|
+
* ```ts
|
|
592
|
+
* collectScrollRegions(document.documentElement).map((region) => region.id)
|
|
593
|
+
* collectScrollRegions(document.documentElement, 'inline').map((region) => region.id)
|
|
594
|
+
* ```
|
|
595
|
+
*/
|
|
596
|
+
export declare function collectScrollRegions(root: Element, axis?: 'inline' | 'block'): readonly HTMLElement[];
|
|
597
|
+
|
|
598
|
+
/**
|
|
599
|
+
* Collects the elements of a region that a forward Tab walk reaches from a starting element.
|
|
600
|
+
*
|
|
601
|
+
* @param root - The region whose stops are collected; the walk ends where focus leaves it.
|
|
602
|
+
* @param start - The element that takes focus first. It is not a stop, and it need not sit in
|
|
603
|
+
* the region.
|
|
604
|
+
* @returns The region's Tab stops in order, including a scroll container Chromium focuses
|
|
605
|
+
* automatically.
|
|
606
|
+
* @throws Thrown when `start` cannot take focus, and whatever {@link walkFocus} throws.
|
|
607
|
+
*
|
|
608
|
+
* @remarks
|
|
609
|
+
* The walk is {@link walkFocus} from `start` with the region's edge as its stop, so a stop outside
|
|
610
|
+
* `root` ends the walk and is left out of the result. A stop belongs to the region by
|
|
611
|
+
* {@link containsNode}, so a control inside an open shadow root or a same-origin frame that `root`
|
|
612
|
+
* holds is in the region, and `start` may sit inside one. A `start` that sits outside the region,
|
|
613
|
+
* as the control immediately before it, is the walk's origin and never its end, so the first Tab into the
|
|
614
|
+
* region reaches its first stop.
|
|
615
|
+
*
|
|
616
|
+
* @example
|
|
617
|
+
* ```ts
|
|
618
|
+
* const stops = await collectTabStops(screen, heading)
|
|
619
|
+
* ```
|
|
620
|
+
*/
|
|
621
|
+
export declare function collectTabStops(root: Element, start: HTMLElement): Promise<readonly HTMLElement[]>;
|
|
622
|
+
|
|
483
623
|
/**
|
|
484
624
|
* Represents one rendered color as straight sRGB channels and its alpha.
|
|
485
625
|
*
|
|
@@ -566,6 +706,26 @@ export declare function computeNamePattern(name: string): RegExp;
|
|
|
566
706
|
*/
|
|
567
707
|
export declare function computeOffset(box: DOMRectReadOnly, width: number, height: number): FrameOffset;
|
|
568
708
|
|
|
709
|
+
/**
|
|
710
|
+
* Determines whether a node sits inside a root, through open shadow roots and frames.
|
|
711
|
+
*
|
|
712
|
+
* @param root - The node that bounds the region.
|
|
713
|
+
* @param node - The node to place.
|
|
714
|
+
* @returns `true` when `node` is `root` or a descendant of it, counting a shadow root's content as
|
|
715
|
+
* its host's and a frame's content as its frame element's.
|
|
716
|
+
*
|
|
717
|
+
* @remarks
|
|
718
|
+
* `contains` stops at a shadow root and at a frame, so a control inside a component reads as outside
|
|
719
|
+
* the region that holds the component. This climbs from the node to its host or its frame element
|
|
720
|
+
* until `contains` answers or the page's top is reached.
|
|
721
|
+
*
|
|
722
|
+
* @example
|
|
723
|
+
* ```ts
|
|
724
|
+
* containsNode(region, readActiveElement() ?? region)
|
|
725
|
+
* ```
|
|
726
|
+
*/
|
|
727
|
+
export declare function containsNode(root: Node, node: Node): boolean;
|
|
728
|
+
|
|
569
729
|
/**
|
|
570
730
|
* Names the roles whose accessible name is the text a reader can see inside them.
|
|
571
731
|
*
|
|
@@ -593,6 +753,22 @@ export declare interface ContrastFixture {
|
|
|
593
753
|
readonly accepted: HTMLElement;
|
|
594
754
|
}
|
|
595
755
|
|
|
756
|
+
/**
|
|
757
|
+
* Configures one color contrast reading: the surface the backdrop walk ends on, and the opacity the
|
|
758
|
+
* painted color is shown at.
|
|
759
|
+
*
|
|
760
|
+
* @remarks
|
|
761
|
+
* Omit `floor` to refuse a stack whose walk reaches no opaque layer, exactly as `readContrast` does.
|
|
762
|
+
* `opacity` multiplies the color's own alpha before it is composited, so a mark painted in a
|
|
763
|
+
* translucent element reads at the strength a reader sees.
|
|
764
|
+
*/
|
|
765
|
+
export declare interface ContrastOptions {
|
|
766
|
+
/** Holds the opaque color the backdrop walk ends on when nothing above it paints. */
|
|
767
|
+
readonly floor?: Color;
|
|
768
|
+
/** Holds the factor, from `0` to `1`, the color's alpha is multiplied by. Default: `1`. */
|
|
769
|
+
readonly opacity?: number;
|
|
770
|
+
}
|
|
771
|
+
|
|
596
772
|
/**
|
|
597
773
|
* Converts encoded A98 RGB channels to clipped sRGB paint channels.
|
|
598
774
|
*
|
|
@@ -780,6 +956,25 @@ export declare function convertXYZD50(x: number, y: number, z: number, alpha?: n
|
|
|
780
956
|
*/
|
|
781
957
|
export declare function convertXYZD65(x: number, y: number, z: number, alpha?: number): Color;
|
|
782
958
|
|
|
959
|
+
/**
|
|
960
|
+
* Counts the elements a tree holds, descending into open shadow roots and same-origin frames.
|
|
961
|
+
*
|
|
962
|
+
* @param root - The document or open shadow root to count. Default: the page's document.
|
|
963
|
+
* @returns How many elements the tree holds, each host and frame element included.
|
|
964
|
+
*
|
|
965
|
+
* @remarks
|
|
966
|
+
* `querySelectorAll('*')` stops at the first boundary, so it undercounts a page built from shadow
|
|
967
|
+
* roots. A frame from another origin and a closed shadow root hold nothing the page can count, so
|
|
968
|
+
* each counts as its own element only. The number bounds a walk that visits each element once, which
|
|
969
|
+
* is how {@link walkFocus} knows a Tab order that never ends.
|
|
970
|
+
*
|
|
971
|
+
* @example
|
|
972
|
+
* ```ts
|
|
973
|
+
* countElements(host.shadowRoot)
|
|
974
|
+
* ```
|
|
975
|
+
*/
|
|
976
|
+
export declare function countElements(root?: Document | ShadowRoot): number;
|
|
977
|
+
|
|
783
978
|
/**
|
|
784
979
|
* Creates one console channel that records every call it receives and hands that call on unchanged.
|
|
785
980
|
*
|
|
@@ -822,8 +1017,11 @@ export declare function createChannel(name: string, output: string[], forward: (
|
|
|
822
1017
|
* The platform declares the `dataTransfer` member on the constructed event as nullable, so calling
|
|
823
1018
|
* code still narrows it even though this always supplies one.
|
|
824
1019
|
*
|
|
825
|
-
* `bubbles` and `
|
|
826
|
-
* is a drop the browser handles itself
|
|
1020
|
+
* `bubbles`, `cancelable`, and `composed` are set, because a drop handler that never prevents the
|
|
1021
|
+
* default event is a drop the browser handles itself, and a drag a browser raises inside an open
|
|
1022
|
+
* shadow root is heard outside it. `composed` defaults to `true` from 0.0.27; 0.0.26 left it
|
|
1023
|
+
* `false`, so an event dispatched inside an open shadow root stayed there. A listener outside that
|
|
1024
|
+
* root hears the event, and `{ composed: false }` restores the 0.0.26 boundary behavior.
|
|
827
1025
|
*
|
|
828
1026
|
* @example
|
|
829
1027
|
* ```ts
|
|
@@ -913,6 +1111,31 @@ export declare function createHarness<TState extends string, TEvent extends stri
|
|
|
913
1111
|
*/
|
|
914
1112
|
export declare function createJournal(): JournalInterface;
|
|
915
1113
|
|
|
1114
|
+
/**
|
|
1115
|
+
* Creates one real keyboard event, ready to dispatch.
|
|
1116
|
+
*
|
|
1117
|
+
* @param name - The event type, such as `keydown`.
|
|
1118
|
+
* @param options - Any `KeyboardEventInit` member, each one overriding the default beneath it.
|
|
1119
|
+
* @returns A real `KeyboardEvent` of that type.
|
|
1120
|
+
*
|
|
1121
|
+
* @remarks
|
|
1122
|
+
* A bare `new KeyboardEvent('keydown')` neither bubbles nor can be cancelled, and it stops at the
|
|
1123
|
+
* first shadow root it meets, so a delegated listener never hears it and `preventDefault` does
|
|
1124
|
+
* nothing, which is the shape that passes in a test and fails in a browser. `bubbles`, `cancelable`,
|
|
1125
|
+
* and `composed` are set, as a browser's own key event carries them. Override any of them by naming
|
|
1126
|
+
* it; every other member, such as `key`, `code`, and the modifiers, is the platform's own and is
|
|
1127
|
+
* named in `options`.
|
|
1128
|
+
*
|
|
1129
|
+
* The event is real rather than a shaped object, so `instanceof KeyboardEvent` holds and the members
|
|
1130
|
+
* a handler reads are the ones the platform defines.
|
|
1131
|
+
*
|
|
1132
|
+
* @example
|
|
1133
|
+
* ```ts
|
|
1134
|
+
* element.dispatchEvent(createKeyboardEvent('keydown', { key: 'Escape' }))
|
|
1135
|
+
* ```
|
|
1136
|
+
*/
|
|
1137
|
+
export declare function createKeyboardEvent(name: string, options?: KeyboardEventInit): KeyboardEvent;
|
|
1138
|
+
|
|
916
1139
|
/**
|
|
917
1140
|
* Creates one real pointer event, ready to dispatch.
|
|
918
1141
|
*
|
|
@@ -922,10 +1145,15 @@ export declare function createJournal(): JournalInterface;
|
|
|
922
1145
|
*
|
|
923
1146
|
* @remarks
|
|
924
1147
|
* The defaults are what a browser's own pointer event carries and a hand-built one does not:
|
|
925
|
-
* `bubbles` and `
|
|
926
|
-
* and
|
|
927
|
-
*
|
|
928
|
-
*
|
|
1148
|
+
* `bubbles`, `cancelable`, and `composed` are set, so a delegated listener hears it, a handler can
|
|
1149
|
+
* prevent it, and a listener outside an open shadow root hears one dispatched inside it, and
|
|
1150
|
+
* `pointerId`, `pointerType`, and `isPrimary` describe a single primary mouse, so a component that
|
|
1151
|
+
* branches on the pointer kind takes the branch a mouse takes. Override any of them by naming it; a
|
|
1152
|
+
* touch is `{ pointerType: 'touch' }` and nothing else has to be restated.
|
|
1153
|
+
*
|
|
1154
|
+
* `composed` defaults to `true` from 0.0.27; 0.0.26 left it `false`, so an event dispatched inside an
|
|
1155
|
+
* open shadow root stayed there. A listener outside that root hears the event, and
|
|
1156
|
+
* `{ composed: false }` restores the 0.0.26 boundary behavior.
|
|
929
1157
|
*
|
|
930
1158
|
* The event is real rather than a shaped object, so `instanceof PointerEvent` holds and the
|
|
931
1159
|
* coordinate and modifier members a handler reads are the ones the platform defines.
|
|
@@ -1036,6 +1264,27 @@ export declare function createStorage(options?: StorageOptions): WebStorageInter
|
|
|
1036
1264
|
*/
|
|
1037
1265
|
export declare function describeFocus(element: Element): string;
|
|
1038
1266
|
|
|
1267
|
+
/**
|
|
1268
|
+
* Describes the window's scroll position and each scroll region's offsets and extents.
|
|
1269
|
+
*
|
|
1270
|
+
* @param regions - The regions to describe, as {@link collectScrollRegions} returns them.
|
|
1271
|
+
* @returns One line for the window, then one line per region with each offset beside the largest
|
|
1272
|
+
* offset that region reaches, or a line saying no region overflows.
|
|
1273
|
+
*
|
|
1274
|
+
* @remarks
|
|
1275
|
+
* The window line reads `window <w>x<h> scroll <x>,<y> of <x>,<y>`. Each region line reads
|
|
1276
|
+
* `scroll <tag>#<id> "<name>": left <x>/<x> top <y>/<y> box <w>x<h> content <w>x<h>`, where the id
|
|
1277
|
+
* and the accessible name appear only when the region carries them and the name is cut to 40
|
|
1278
|
+
* characters. Record it beside a frame, so the journey's output says which panes scroll and where
|
|
1279
|
+
* each one stood when the picture was taken.
|
|
1280
|
+
*
|
|
1281
|
+
* @example
|
|
1282
|
+
* ```ts
|
|
1283
|
+
* describeScrollRegions(collectScrollRegions(document.documentElement))
|
|
1284
|
+
* ```
|
|
1285
|
+
*/
|
|
1286
|
+
export declare function describeScrollRegions(regions: readonly HTMLElement[]): string;
|
|
1287
|
+
|
|
1039
1288
|
/**
|
|
1040
1289
|
* Describes the accessible tree one rendered element presents.
|
|
1041
1290
|
*
|
|
@@ -1078,9 +1327,10 @@ export declare function describeTree(element: Element): string;
|
|
|
1078
1327
|
* @remarks
|
|
1079
1328
|
* This is the one pointer drive every hold verb shares: the held-marker refusal, a scroll that
|
|
1080
1329
|
* brings a wholly off-viewport target into view and a refusal for one that stays outside, the
|
|
1081
|
-
* centre
|
|
1082
|
-
* and press, the marker, and the frame wait and the `:active` read-back that both
|
|
1083
|
-
* refusing. The refusal precedes resolution, so a double hold is refused before an
|
|
1330
|
+
* centre projected through every frame into page coordinates by {@link readProtocolPoint}, the
|
|
1331
|
+
* trusted move and press, the marker, and the frame wait and the `:active` read-back that both
|
|
1332
|
+
* release before refusing. The refusal precedes resolution, so a double hold is refused before an
|
|
1333
|
+
* absent name is.
|
|
1084
1334
|
*
|
|
1085
1335
|
* @example
|
|
1086
1336
|
* ```ts
|
|
@@ -1101,9 +1351,9 @@ export declare function driveHold(resolve: () => HTMLElement, name: string): Pro
|
|
|
1101
1351
|
* @throws When the resolver refuses, or one complete traversal cannot reach the target.
|
|
1102
1352
|
*
|
|
1103
1353
|
* @remarks
|
|
1104
|
-
* This is the one loop every traversal verb shares. A step counts only when
|
|
1105
|
-
* element, the traversal is over when focus revisits one, and the cap is counted
|
|
1106
|
-
* {@link FOCUSABLE_SELECTOR}.
|
|
1354
|
+
* This is the one loop every traversal verb shares, over {@link stepFocus}. A step counts only when
|
|
1355
|
+
* focus lands on an element, the traversal is over when focus revisits one, and the cap is counted
|
|
1356
|
+
* off {@link FOCUSABLE_SELECTOR}.
|
|
1107
1357
|
*
|
|
1108
1358
|
* @example
|
|
1109
1359
|
* ```ts
|
|
@@ -1737,8 +1987,9 @@ export declare function matchesColor(first: string | Color, second: string | Col
|
|
|
1737
1987
|
*
|
|
1738
1988
|
* Each element contributes its client rectangle's bottom edge in document coordinates plus its own
|
|
1739
1989
|
* bottom margin, which sits outside that rectangle, and the largest contribution wins. An ancestor
|
|
1740
|
-
* that clips its overflow
|
|
1741
|
-
*
|
|
1990
|
+
* that clips its overflow, which the {@link collectClippingAncestors} helper finds through the flat
|
|
1991
|
+
* tree and so reaches a shadow wrapper around a slot, caps the contribution at that ancestor's clip
|
|
1992
|
+
* edge, which the {@link readClipEdge} helper measures, because the rows a descendant lays out past a clipping
|
|
1742
1993
|
* frame are cut, scrolled, or discarded rather than added to the document: a viewport-height
|
|
1743
1994
|
* specimen inside a bounded frame ends, for this reading, where the frame ends, so a taller pane
|
|
1744
1995
|
* does not read back as a taller document. The clip edge of a `clip` overflow, and of a paint
|
|
@@ -1798,11 +2049,13 @@ export declare function measureLuminance(color: Color): number;
|
|
|
1798
2049
|
*
|
|
1799
2050
|
* @remarks
|
|
1800
2051
|
* The value is a bit string in print, reduced motion, dark colour scheme, and forced colours order.
|
|
1801
|
-
* Each bit is `1` for a matching query and `0` otherwise, for example `0100`.
|
|
2052
|
+
* Each bit is `1` for a matching query and `0` otherwise, for example `0100`. The first pointer
|
|
2053
|
+
* stage appends a fifth bit for the pre-call `(pointer: coarse)` reading. Without a pointer stage,
|
|
2054
|
+
* the marker stays four bits and release leaves touch emulation alone.
|
|
1802
2055
|
*/
|
|
1803
2056
|
export declare const MEDIA_STAGE = "data-media-stage";
|
|
1804
2057
|
|
|
1805
|
-
/** Configures the tester's print medium, motion preference, and
|
|
2058
|
+
/** Configures the tester's print medium, motion preference, forced colours, and pointer precision. */
|
|
1806
2059
|
export declare interface MediaOptions {
|
|
1807
2060
|
/** Determines whether the tester lays out for print. Omit it to leave the medium alone. */
|
|
1808
2061
|
readonly print?: boolean;
|
|
@@ -1810,6 +2063,8 @@ export declare interface MediaOptions {
|
|
|
1810
2063
|
readonly motion?: boolean;
|
|
1811
2064
|
/** Determines whether the tester runs under forced colours. Omit it to leave the colours alone. */
|
|
1812
2065
|
readonly forced?: boolean;
|
|
2066
|
+
/** Selects touch emulation for coarse input or mouse input for fine precision. Omit it to leave touch emulation alone. */
|
|
2067
|
+
readonly pointer?: 'coarse' | 'fine';
|
|
1813
2068
|
}
|
|
1814
2069
|
|
|
1815
2070
|
/**
|
|
@@ -1841,6 +2096,53 @@ export declare interface MediaOptions {
|
|
|
1841
2096
|
*/
|
|
1842
2097
|
export declare function mount<T extends Element>(element: T): T;
|
|
1843
2098
|
|
|
2099
|
+
/**
|
|
2100
|
+
* Decodes a base64 PNG and paints it, unscaled, onto a fresh offscreen 2D canvas.
|
|
2101
|
+
*
|
|
2102
|
+
* @param encoded - The image's bytes as base64 text, without a data-URL prefix.
|
|
2103
|
+
* @returns The canvas's 2D context, whose `canvas` holds the image's size in device pixels, or
|
|
2104
|
+
* `undefined` when the browser hands out no 2D context.
|
|
2105
|
+
* @throws The decode failure, as the rejection of the image's own `decode` call, when the bytes are
|
|
2106
|
+
* not an image this browser decodes.
|
|
2107
|
+
*
|
|
2108
|
+
* @remarks
|
|
2109
|
+
* This is the decode and the draw that {@link readFrame} and {@link readShotPixel} share, which
|
|
2110
|
+
* leaves each of them its own words for a refusal: a frame names the path it was read from and the
|
|
2111
|
+
* size its header declares, and a shot names neither. The decode failure is handed on unchanged so
|
|
2112
|
+
* the caller can read the bytes it rejected, and the missing context is a value rather than a throw
|
|
2113
|
+
* for the same reason. The image is drawn at its natural size, so the canvas holds one canvas pixel
|
|
2114
|
+
* for each device pixel of the image.
|
|
2115
|
+
*
|
|
2116
|
+
* @example
|
|
2117
|
+
* ```ts
|
|
2118
|
+
* const context = await paintImage(encoded)
|
|
2119
|
+
* const [red, green, blue] = context?.getImageData(0, 0, 1, 1).data ?? []
|
|
2120
|
+
* ```
|
|
2121
|
+
*/
|
|
2122
|
+
export declare function paintImage(encoded: string): Promise<OffscreenCanvasRenderingContext2D | undefined>;
|
|
2123
|
+
|
|
2124
|
+
/**
|
|
2125
|
+
* Parks the pointer outside the page and waits for the parked pointer's frame to paint.
|
|
2126
|
+
*
|
|
2127
|
+
* @returns A promise resolving after the pointer has moved to its park point and one frame has painted.
|
|
2128
|
+
* @throws Thrown when the provider exposes no DevTools session, or the move rejects.
|
|
2129
|
+
*
|
|
2130
|
+
* @remarks
|
|
2131
|
+
* The park point is (-1, -1) in the runner page's coordinates, one pixel above and to the left of
|
|
2132
|
+
* that page's viewport. The browser hit-tests nothing outside the viewport, so no element keeps its
|
|
2133
|
+
* hover paint from the parked pointer. This sends no button release: a press that the
|
|
2134
|
+
* `holdAccessible` verb holds stays recorded as held and its button-up is still owed, so a later
|
|
2135
|
+
* `releasePointer` call sends it. The control a held press was on loses its `:active` paint when the
|
|
2136
|
+
* pointer leaves it. Use this verb to clear hover without ending a held press, and
|
|
2137
|
+
* `releasePointer` for teardown.
|
|
2138
|
+
*
|
|
2139
|
+
* @example
|
|
2140
|
+
* ```ts
|
|
2141
|
+
* await parkPointer()
|
|
2142
|
+
* ```
|
|
2143
|
+
*/
|
|
2144
|
+
export declare function parkPointer(): Promise<void>;
|
|
2145
|
+
|
|
1844
2146
|
/**
|
|
1845
2147
|
* Parses computed CSS Color 4 values into clipped straight sRGB channels.
|
|
1846
2148
|
*
|
|
@@ -1869,34 +2171,55 @@ export declare function parseColor(value: string): Color | undefined;
|
|
|
1869
2171
|
*
|
|
1870
2172
|
* @param value - Any value the `color` property accepts: a keyword, a hex triple, a `var()`
|
|
1871
2173
|
* reference, a `color-mix()`, or a computed CSS Color 4 value.
|
|
1872
|
-
* @
|
|
1873
|
-
*
|
|
2174
|
+
* @param scope - The element whose cascade the expression resolves in. Omit it to resolve at the
|
|
2175
|
+
* document's body.
|
|
2176
|
+
* @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value, the
|
|
2177
|
+
* computed result names no color {@link parseColor} speaks, or the scope is disconnected and
|
|
2178
|
+
* computes no style.
|
|
1874
2179
|
*
|
|
1875
2180
|
* @remarks
|
|
1876
2181
|
* This is the live half of the pair {@link parseColor} opens. `parseColor` reads text and speaks
|
|
1877
|
-
* only the computed syntaxes a cascade hands back; this
|
|
1878
|
-
*
|
|
1879
|
-
*
|
|
2182
|
+
* only the computed syntaxes a cascade hands back; this hands the expression to the real cascade
|
|
2183
|
+
* and reads back what the engine computed — which is the only way a keyword, a hex triple, or a
|
|
2184
|
+
* `var()` reference becomes channels at all. The read itself goes through `parseColor`, so both
|
|
1880
2185
|
* halves agree on what a computed value means.
|
|
1881
2186
|
* Modern perceptual and predefined RGB/XYZ spaces resolve through that parser's conversions;
|
|
1882
2187
|
* out-of-gamut sRGB channels are clipped to 0–255 after conversion.
|
|
1883
2188
|
*
|
|
1884
|
-
*
|
|
1885
|
-
*
|
|
1886
|
-
*
|
|
2189
|
+
* With no scope the expression resolves on a probe that is a child of `document.body`, mounted
|
|
2190
|
+
* because an unmounted element inherits nothing, so a `var()` reference or `currentColor` resolves
|
|
2191
|
+
* against what the body declares and paints. The probe is removed in a `finally`, so a value that
|
|
2192
|
+
* throws on the way through leaves no node behind.
|
|
2193
|
+
*
|
|
2194
|
+
* With a scope the expression resolves on that same body-mounted probe, which carries the scope's
|
|
2195
|
+
* computed context onto its own inline style: the computed value of every custom property the
|
|
2196
|
+
* expression names, a fallback's included, the scope's computed `color`, and its computed
|
|
2197
|
+
* `color-scheme`. The expression is written into `background-color`, so `currentColor` is the
|
|
2198
|
+
* carried `color`, and a system color or `light-dark()` answers as the scope's scheme. The element's
|
|
2199
|
+
* own and inherited custom properties therefore apply, a registered property that does not inherit
|
|
2200
|
+
* included, and an `input`, an SVG element, or any other element resolves like any other. A custom
|
|
2201
|
+
* property is named by letters, digits, `_`, and `-` after its `--`. A name the scope leaves
|
|
2202
|
+
* undeclared is not carried, so its `var()` fallback still applies.
|
|
2203
|
+
*
|
|
2204
|
+
* The scope element is never written. The probe is new, so it has no earlier style to start a
|
|
2205
|
+
* transition from, and a transition running on the scope keeps running: `currentColor` reads the
|
|
2206
|
+
* color the scope shows at that moment, and the scope's geometry and scroll position stay as they
|
|
2207
|
+
* were. No attribute, style, or child of the scope changes, so a `MutationObserver` on it records
|
|
2208
|
+
* nothing.
|
|
1887
2209
|
*
|
|
1888
|
-
* Refusal is the CSSOM's: an expression it will not parse leaves the probe's
|
|
1889
|
-
*
|
|
1890
|
-
*
|
|
2210
|
+
* Refusal is the CSSOM's: an expression it will not parse leaves the probe's declaration empty and
|
|
2211
|
+
* this returns `undefined`. A `var()` naming an undeclared custom property is not refused, because
|
|
2212
|
+
* the cascade accepts it and computes the inherited color, so a test that means to catch a
|
|
1891
2213
|
* missing token asserts on {@link readToken} rather than on this.
|
|
1892
2214
|
*
|
|
1893
2215
|
* @example
|
|
1894
2216
|
* ```ts
|
|
1895
2217
|
* parseCSSColor('rebeccapurple') // [102, 51, 153, 1]
|
|
1896
2218
|
* parseCSSColor('not-a-color') // undefined
|
|
2219
|
+
* parseCSSColor('var(--ink)', panel) // the token as the panel declares it
|
|
1897
2220
|
* ```
|
|
1898
2221
|
*/
|
|
1899
|
-
export declare function parseCSSColor(value: string): Color | undefined;
|
|
2222
|
+
export declare function parseCSSColor(value: string, scope?: Element): Color | undefined;
|
|
1900
2223
|
|
|
1901
2224
|
/**
|
|
1902
2225
|
* Names the tester root's attribute holding the pressed pointer's page coordinates.
|
|
@@ -1979,6 +2302,93 @@ export declare interface PortfolioOptions {
|
|
|
1979
2302
|
*/
|
|
1980
2303
|
export declare function pressKeys(keys: string): Promise<void>;
|
|
1981
2304
|
|
|
2305
|
+
/**
|
|
2306
|
+
* Represents one point in the coordinates of the browser's top-level viewport, the space a DevTools
|
|
2307
|
+
* input command addresses.
|
|
2308
|
+
*
|
|
2309
|
+
* @remarks
|
|
2310
|
+
* As an input to {@link readProtocolPoint}, the same shape names an offset from the element's
|
|
2311
|
+
* top-left corner, in the element's own pixels.
|
|
2312
|
+
*/
|
|
2313
|
+
export declare interface ProtocolPoint {
|
|
2314
|
+
/** Holds the distance from the left edge, in CSS pixels. */
|
|
2315
|
+
readonly x: number;
|
|
2316
|
+
/** Holds the distance from the top edge, in CSS pixels. */
|
|
2317
|
+
readonly y: number;
|
|
2318
|
+
}
|
|
2319
|
+
|
|
2320
|
+
/**
|
|
2321
|
+
* Reads the accessibility node the browser computed for one element.
|
|
2322
|
+
*
|
|
2323
|
+
* @param element - The connected element to read.
|
|
2324
|
+
* @returns A promise resolving to the node's role, name, and properties.
|
|
2325
|
+
* @throws Thrown when the provider exposes no DevTools session, a command fails, or the element is
|
|
2326
|
+
* not the one connected element {@link readProtocolNode} finds.
|
|
2327
|
+
*
|
|
2328
|
+
* @remarks
|
|
2329
|
+
* This is the browser's own computation, which complements the DOM-based `readRole`, `readName`, and
|
|
2330
|
+
* `readStates`: those apply this package's mapping to the markup, and this asks the browser what it
|
|
2331
|
+
* published. A property whose value names other nodes reads as the list of their ids, and a value the
|
|
2332
|
+
* browser states plainly reads as that value.
|
|
2333
|
+
*
|
|
2334
|
+
* @example
|
|
2335
|
+
* ```ts
|
|
2336
|
+
* const node = await readAccessibilityNode(input)
|
|
2337
|
+
* node.name // 'Port'
|
|
2338
|
+
* ```
|
|
2339
|
+
*/
|
|
2340
|
+
export declare function readAccessibilityNode(element: Element): Promise<AccessibilityNode>;
|
|
2341
|
+
|
|
2342
|
+
/**
|
|
2343
|
+
* Reads the HTML element that holds focus, following it into open shadow roots and same-origin
|
|
2344
|
+
* frames.
|
|
2345
|
+
*
|
|
2346
|
+
* @param root - The document or open shadow root to read from. Default: the page's document.
|
|
2347
|
+
* @returns The innermost focused element when it is an HTML element of its own window, or
|
|
2348
|
+
* `undefined` when only a body, a non-HTML element, or nothing holds focus.
|
|
2349
|
+
* @throws Thrown when focus sits in a frame from another origin, whose document the page cannot
|
|
2350
|
+
* reach.
|
|
2351
|
+
*
|
|
2352
|
+
* @remarks
|
|
2353
|
+
* `document.activeElement` stops at the first boundary: it names the host of a shadow root or the
|
|
2354
|
+
* element of a frame, never the control focused inside. This follows `shadowRoot.activeElement` and
|
|
2355
|
+
* a frame's `contentDocument.activeElement` until neither names a deeper element, so a host or a
|
|
2356
|
+
* frame holding focus with nothing focused inside is itself the answer. A closed shadow root cannot
|
|
2357
|
+
* be followed, so its host is the answer there. When the innermost focused element is not HTML, as
|
|
2358
|
+
* an SVG element focused inside an open shadow root, the answer is `undefined`: the host that holds
|
|
2359
|
+
* it is not where focus is.
|
|
2360
|
+
*
|
|
2361
|
+
* A frame from another origin is refused rather than answered with its element, because the answer
|
|
2362
|
+
* would name a frame while focus sat on a control the page cannot see. The element comes back typed
|
|
2363
|
+
* for its own window, so a control inside a frame passes the frame's `HTMLElement` check and not
|
|
2364
|
+
* this window's.
|
|
2365
|
+
*
|
|
2366
|
+
* @example
|
|
2367
|
+
* ```ts
|
|
2368
|
+
* readActiveElement()?.textContent
|
|
2369
|
+
* ```
|
|
2370
|
+
*/
|
|
2371
|
+
export declare function readActiveElement(root?: Document | ShadowRoot): HTMLElement | undefined;
|
|
2372
|
+
|
|
2373
|
+
/**
|
|
2374
|
+
* Reads the animations running on one element and its subtree, split by whether each one ends.
|
|
2375
|
+
*
|
|
2376
|
+
* @param element - The element whose own animations and descendants' animations to read.
|
|
2377
|
+
* @returns The running animations that end, and the running animations whose effect declares
|
|
2378
|
+
* infinite iterations.
|
|
2379
|
+
*
|
|
2380
|
+
* @remarks
|
|
2381
|
+
* The split is the one {@link waitForAnimations} waits by: it waits on `finite` and leaves
|
|
2382
|
+
* `endless` running. A paused, an idle, and a finished animation are at rest, so neither
|
|
2383
|
+
* list holds one. A detached element runs no animation and reads as two empty lists.
|
|
2384
|
+
*
|
|
2385
|
+
* @example
|
|
2386
|
+
* ```ts
|
|
2387
|
+
* readAnimations(document.documentElement).finite.length // 0 once every transition has settled
|
|
2388
|
+
* ```
|
|
2389
|
+
*/
|
|
2390
|
+
export declare function readAnimations(element: Element): AnimationReading;
|
|
2391
|
+
|
|
1982
2392
|
/**
|
|
1983
2393
|
* Resolves the opaque color standing behind one element.
|
|
1984
2394
|
*
|
|
@@ -2026,6 +2436,14 @@ export declare function readBackdrop(element: Element, floor: Color): Color;
|
|
|
2026
2436
|
* stack and inserted the deepest rule first. Iterate the set where the order is the subject, and
|
|
2027
2437
|
* read `has` where membership is.
|
|
2028
2438
|
*
|
|
2439
|
+
* Each rule's selector text is read by {@link collectSelectorClasses}, so the tokens are the class
|
|
2440
|
+
* names a selector means rather than what a pattern over its text finds: an escaped name decodes,
|
|
2441
|
+
* so `.sm\:flex` defines `sm:flex` rather than `sm`; text inside an attribute value, a string, or
|
|
2442
|
+
* a comment defines nothing, so `[title=".card"]` defines no `card`; and a name opening with an
|
|
2443
|
+
* underscore, a hyphen, or a non-ASCII letter counts, and a non-ASCII letter inside a name stays in
|
|
2444
|
+
* it, so `.café` defines `café` where 0.0.26 ended the class at the first code point outside ASCII
|
|
2445
|
+
* letters, digits, `_`, and `-` and defined `caf`. One rule's own tokens enter in code-unit order.
|
|
2446
|
+
*
|
|
2029
2447
|
* `@keyframes` children are outside that walk, so an animation's own rules define no token here.
|
|
2030
2448
|
* Reach the animation itself through {@link findKeyframes}.
|
|
2031
2449
|
*
|
|
@@ -2139,6 +2557,77 @@ export declare function readClipEdge(element: Element): number | undefined;
|
|
|
2139
2557
|
*/
|
|
2140
2558
|
export declare function readClipMargin(element: Element): number;
|
|
2141
2559
|
|
|
2560
|
+
/**
|
|
2561
|
+
* Measures the block size an element shows after every clipping ancestor cuts it.
|
|
2562
|
+
*
|
|
2563
|
+
* @param element - The element to read.
|
|
2564
|
+
* @returns The height in CSS pixels of the part of the element's box that lies inside the clip of
|
|
2565
|
+
* every ancestor that clips its overflow, and `0` where none of it does.
|
|
2566
|
+
* @throws Thrown when the element is not connected to a document.
|
|
2567
|
+
*
|
|
2568
|
+
* @remarks
|
|
2569
|
+
* The `getBoundingClientRect` method reports the whole box of a clipped element, so a bar taller
|
|
2570
|
+
* than its frame still reads its own height there; this reading is the height a person sees. An
|
|
2571
|
+
* ancestor clips where the {@link clipsOverflow} helper says so, and the {@link collectClippingAncestors}
|
|
2572
|
+
* helper finds it through the flat tree, so a wrapper in a shadow tree around the element or around
|
|
2573
|
+
* its slot counts. Its top edge is the top of its
|
|
2574
|
+
* padding box, and its bottom edge is the one the {@link readClipEdge} helper measures, so a paint
|
|
2575
|
+
* containment and an `overflow-clip-margin` length count. That edge comes in document coordinates
|
|
2576
|
+
* and is converted into the viewport coordinates the box is read in, so a scrolled page reads the
|
|
2577
|
+
* same height as an unscrolled one.
|
|
2578
|
+
*
|
|
2579
|
+
* @example
|
|
2580
|
+
* ```ts
|
|
2581
|
+
* readClippedBlock(bar) // the frame's height where the frame clips a taller bar
|
|
2582
|
+
* ```
|
|
2583
|
+
*/
|
|
2584
|
+
export declare function readClippedBlock(element: Element): number;
|
|
2585
|
+
|
|
2586
|
+
/**
|
|
2587
|
+
* Measures the WCAG 2.x contrast ratio one color reaches when painted over an element's backdrop.
|
|
2588
|
+
*
|
|
2589
|
+
* @param element - The element whose own and ancestor backgrounds paint the surface.
|
|
2590
|
+
* @param color - Any CSS color expression, such as the resolved `border-left-color` of a
|
|
2591
|
+
* pseudo-element, resolved at the element's own scope.
|
|
2592
|
+
* @param options - The floor the backdrop walk ends on and the opacity the color is shown at.
|
|
2593
|
+
* @returns The ratio of the color composited over the backdrop, against that backdrop.
|
|
2594
|
+
* @throws Thrown when `color` names no readable color, as under a disconnected element that computes
|
|
2595
|
+
* no style, when `opacity` lies outside `0` to `1`, when a painted background layer is unreadable,
|
|
2596
|
+
* and — with `floor` omitted — when the walk from the element upwards reaches no opaque layer.
|
|
2597
|
+
*
|
|
2598
|
+
* @remarks
|
|
2599
|
+
* This is the reading {@link readContrast} and {@link readRing} take for their own colors, with the
|
|
2600
|
+
* color handed in: a separator grip, a placeholder, a checkbox mark, or any other paint that is not
|
|
2601
|
+
* the element's text. The backdrop composites the {@link readLayers} stack top-over-bottom, the
|
|
2602
|
+
* color composites over that backdrop, and the ratio is measured between the two, so a translucent
|
|
2603
|
+
* color reads at the strength a reader sees.
|
|
2604
|
+
*
|
|
2605
|
+
* A computed color value parses directly through {@link parseColor}; any other expression, such as
|
|
2606
|
+
* a keyword or a `var()` reference, resolves through {@link parseCSSColor} at the element's own
|
|
2607
|
+
* scope. A `var()` reference therefore reads the token as the element and its ancestors declare it,
|
|
2608
|
+
* and `currentColor` reads the element's own text color, not the body's. The read carries the
|
|
2609
|
+
* element's computed custom properties, `color`, and `color-scheme` onto a probe, so an `input` and
|
|
2610
|
+
* a non-inheriting registered token resolve as they do on any other element, and the element itself
|
|
2611
|
+
* is never written. A disconnected element computes no style, so it reads no expression; hand it a
|
|
2612
|
+
* computed color such as `rgb(255, 255, 255)`.
|
|
2613
|
+
*
|
|
2614
|
+
* With `options.floor` omitted, the walk must reach a fully opaque layer, and the refusal shares
|
|
2615
|
+
* `readContrast`'s voice, because the number a stack the canvas shows through produces is as much a
|
|
2616
|
+
* report of the assumption as of the page. Name the floor wherever the caller knows what the stack
|
|
2617
|
+
* sits on: {@link CANVAS_COLOR} for a document, or the color a fragment is really mounted onto.
|
|
2618
|
+
* `options.opacity` multiplies the color's alpha before compositing, for a mark painted inside an
|
|
2619
|
+
* element whose own `opacity` is below `1`. Default: `1`.
|
|
2620
|
+
*
|
|
2621
|
+
* @example
|
|
2622
|
+
* ```ts
|
|
2623
|
+
* const container = render('<div style="background: #fff"><span>Mark</span></div>')
|
|
2624
|
+
* const mark = requireValue(container.querySelector('span'))
|
|
2625
|
+
* readColorContrast(mark, 'rgb(0, 0, 0)') // 21
|
|
2626
|
+
* readColorContrast(mark, 'rgb(0, 0, 0)', { opacity: 0.5 }) // the rgba(0, 0, 0, 0.5) reading
|
|
2627
|
+
* ```
|
|
2628
|
+
*/
|
|
2629
|
+
export declare function readColorContrast(element: Element, color: string, options?: ContrastOptions): number;
|
|
2630
|
+
|
|
2142
2631
|
/**
|
|
2143
2632
|
* Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
|
|
2144
2633
|
*
|
|
@@ -2170,7 +2659,8 @@ export declare function readClipMargin(element: Element): number;
|
|
|
2170
2659
|
* over it rather than refused.
|
|
2171
2660
|
*
|
|
2172
2661
|
* The element itself must expose a computed foreground color either way. A detached element exposes
|
|
2173
|
-
* none, and the measurement throws rather than guessing one.
|
|
2662
|
+
* none, and the measurement throws rather than guessing one. The computed foreground is then
|
|
2663
|
+
* measured by {@link readColorContrast}, which owns the walk, the refusal, and the composite.
|
|
2174
2664
|
*
|
|
2175
2665
|
* @example
|
|
2176
2666
|
* ```ts
|
|
@@ -2185,8 +2675,15 @@ export declare function readContrast(element: Element, floor?: Color): number;
|
|
|
2185
2675
|
* Reads the rendered text of the element that holds focus.
|
|
2186
2676
|
*
|
|
2187
2677
|
* @returns The focused HTML element's trimmed rendered text, including an empty string, or
|
|
2188
|
-
* `undefined` when focus rests on a non-HTML element. When nothing holds
|
|
2189
|
-
* reports the document body as active, so the whole page's rendered text returns.
|
|
2678
|
+
* `undefined` when focus rests on a non-HTML element, inside a shadow root or not. When nothing holds
|
|
2679
|
+
* focus, the browser reports the document body as active, so the whole page's rendered text returns.
|
|
2680
|
+
* @throws Thrown when focus sits in a frame from another origin, as {@link readActiveElement} refuses.
|
|
2681
|
+
*
|
|
2682
|
+
* @remarks
|
|
2683
|
+
* The focused element is read through {@link readActiveElement}, so a control focused inside an open
|
|
2684
|
+
* shadow root or a same-origin frame answers, not its host or its frame. The page text returns only
|
|
2685
|
+
* when the document's active element is its body, and never as a fallback for a focused element
|
|
2686
|
+
* that {@link readActiveElement} declines.
|
|
2190
2687
|
*
|
|
2191
2688
|
* @example
|
|
2192
2689
|
* ```ts
|
|
@@ -2284,6 +2781,28 @@ export declare function readFrame(path: string): Promise<FrameReading>;
|
|
|
2284
2781
|
*/
|
|
2285
2782
|
export declare function readHit(element: Element): Element | undefined;
|
|
2286
2783
|
|
|
2784
|
+
/**
|
|
2785
|
+
* Reads layer statements and blocks in declaration order, including repeated names.
|
|
2786
|
+
*
|
|
2787
|
+
* @param source - The parsed sheet, or a grouping or style rule inside it.
|
|
2788
|
+
* @param layer - The qualified name of the layer enclosing the source, when one does.
|
|
2789
|
+
* @returns Qualified layer names, with an empty name for an anonymous top-level layer.
|
|
2790
|
+
*
|
|
2791
|
+
* @remarks
|
|
2792
|
+
* Descends through grouping and style rules at any depth, qualifying each name by its enclosing layer.
|
|
2793
|
+
* An anonymous layer inside a named layer contributes a trailing dot to that qualified name.
|
|
2794
|
+
* Conditions are read whether or not they match the document.
|
|
2795
|
+
* An `@import ... layer()` rule contributes nothing, and neither do its imported sheet's rules.
|
|
2796
|
+
* A dotted declaration such as `@layer a.b` contributes `a.b` as declared, without an implicit `a`.
|
|
2797
|
+
* Distinct anonymous layers produce the same names; the result does not distinguish their identities.
|
|
2798
|
+
*
|
|
2799
|
+
* @example
|
|
2800
|
+
* ```ts
|
|
2801
|
+
* readLayerNames(new CSSStyleSheet()) // []
|
|
2802
|
+
* ```
|
|
2803
|
+
*/
|
|
2804
|
+
export declare function readLayerNames(source: CSSStyleSheet | CSSGroupingRule | CSSStyleRule, layer?: string): readonly string[];
|
|
2805
|
+
|
|
2287
2806
|
/**
|
|
2288
2807
|
* Collects readable background color layers and refuses an unreadable painted layer.
|
|
2289
2808
|
*
|
|
@@ -2408,6 +2927,60 @@ export declare function readPerception(name: string): string;
|
|
|
2408
2927
|
*/
|
|
2409
2928
|
export declare function readPixels(element: Element, property: string, pseudo?: string): number;
|
|
2410
2929
|
|
|
2930
|
+
/**
|
|
2931
|
+
* Resolves one element to the node the browser's DOM tree holds for it.
|
|
2932
|
+
*
|
|
2933
|
+
* @param element - The element to find.
|
|
2934
|
+
* @returns A promise resolving to the DevTools node id of the element.
|
|
2935
|
+
* @throws Thrown when the provider exposes no DevTools session, a command fails, or the element is
|
|
2936
|
+
* not the one connected element its marker finds.
|
|
2937
|
+
*
|
|
2938
|
+
* @remarks
|
|
2939
|
+
* The browser's DOM domain cannot be handed an element, so the element wears a marker attribute while
|
|
2940
|
+
* the browser searches the document, shadow roots included, for it. The search is discarded and the
|
|
2941
|
+
* marker is put back before this resolves: an attribute the element already carried under that name
|
|
2942
|
+
* keeps its value, and an absent one is removed again, on a refusal as much as on success.
|
|
2943
|
+
*
|
|
2944
|
+
* Use the id before calling again, because each call asks the browser for the document afresh. A
|
|
2945
|
+
* twin of the element, left unmarked, is never the node returned.
|
|
2946
|
+
*
|
|
2947
|
+
* @example
|
|
2948
|
+
* ```ts
|
|
2949
|
+
* const nodeId = await readProtocolNode(button)
|
|
2950
|
+
* const described = await sendProtocol('DOM.describeNode', { nodeId })
|
|
2951
|
+
* ```
|
|
2952
|
+
*/
|
|
2953
|
+
export declare function readProtocolNode(element: Element): Promise<number>;
|
|
2954
|
+
|
|
2955
|
+
/**
|
|
2956
|
+
* Projects a point of one element through every frame that holds it into the browser's top-level
|
|
2957
|
+
* viewport.
|
|
2958
|
+
*
|
|
2959
|
+
* @param element - The connected element the point is relative to.
|
|
2960
|
+
* @param offset - The offset from the element's top-left corner, in the element's own pixels.
|
|
2961
|
+
* Default: the centre of its box.
|
|
2962
|
+
* @returns The point in the top-level viewport's coordinates, which is where a DevTools input
|
|
2963
|
+
* command addresses.
|
|
2964
|
+
* @throws Thrown when the element is not connected to a document, or a frame on the way up is not an
|
|
2965
|
+
* HTML element of a document a window holds.
|
|
2966
|
+
*
|
|
2967
|
+
* @remarks
|
|
2968
|
+
* Each frame on the way up adds its border and its padding, which is where its content starts,
|
|
2969
|
+
* scales the point by the ratio of its painted width to its layout width, and adds its own position,
|
|
2970
|
+
* so a tester iframe the runner scales or offsets is accounted for, and so is an iframe the page
|
|
2971
|
+
* itself nests, bordered, padded, or neither. The reading is of the layout now: a box that moves
|
|
2972
|
+
* afterwards moves the point it names. An element in a document no frame holds reads its own client
|
|
2973
|
+
* point. A disconnected element has no layout, and its window still names the tester frame, so it is
|
|
2974
|
+
* refused rather than read as that frame's corner.
|
|
2975
|
+
*
|
|
2976
|
+
* @example
|
|
2977
|
+
* ```ts
|
|
2978
|
+
* const point = readProtocolPoint(button)
|
|
2979
|
+
* await sendProtocol('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point })
|
|
2980
|
+
* ```
|
|
2981
|
+
*/
|
|
2982
|
+
export declare function readProtocolPoint(element: Element, offset?: ProtocolPoint): ProtocolPoint;
|
|
2983
|
+
|
|
2411
2984
|
/**
|
|
2412
2985
|
* Reads the refusal one named target answers with, or nothing when it resolves.
|
|
2413
2986
|
*
|
|
@@ -2458,7 +3031,9 @@ export declare function readRefusal(role: string, name: string): string | undefi
|
|
|
2458
3031
|
* @param worn - The element the control's focus chrome is painted onto. Default: `control`.
|
|
2459
3032
|
* @returns The strongest ratio the painted focus chrome reaches, or `undefined` when the control is
|
|
2460
3033
|
* not showing `:focus-visible` or the cascade paints no chrome of its own.
|
|
2461
|
-
* @throws Thrown when the
|
|
3034
|
+
* @throws Thrown when the control is showing `:focus-visible` and the backdrop behind the element
|
|
3035
|
+
* the chrome is worn on contains an unreadable painted color layer, whether or not the cascade
|
|
3036
|
+
* paints chrome.
|
|
2462
3037
|
*
|
|
2463
3038
|
* @remarks
|
|
2464
3039
|
* This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
|
|
@@ -2471,10 +3046,12 @@ export declare function readRefusal(role: string, name: string): string | undefi
|
|
|
2471
3046
|
* measurement is not taken on a rectangle nobody is looking at. The focus state is still read off
|
|
2472
3047
|
* `control`, because that is what holds it.
|
|
2473
3048
|
*
|
|
2474
|
-
* The backdrop is the surface behind the element the chrome is worn on
|
|
2475
|
-
*
|
|
2476
|
-
* nothing is therefore measured against the browser's own
|
|
2477
|
-
* an unstyled document sees.
|
|
3049
|
+
* The backdrop is the surface behind the element the chrome is worn on: each painted color is
|
|
3050
|
+
* measured by {@link readColorContrast} from that element's parent, with {@link CANVAS_COLOR} as the
|
|
3051
|
+
* floor. A control whose ancestry paints nothing is therefore measured against the browser's own
|
|
3052
|
+
* canvas, which is what a reader looking at an unstyled document sees. The backdrop is read for
|
|
3053
|
+
* every control showing `:focus-visible` before the chrome is looked for, so an unreadable surface
|
|
3054
|
+
* refuses the reading even where the cascade paints no chrome.
|
|
2478
3055
|
*
|
|
2479
3056
|
* Only chrome the cascade paints is measured — an `outline` with a real style and width, and the
|
|
2480
3057
|
* first color in a `box-shadow`. A control left the browser's own `outline-style: auto` ring reports
|
|
@@ -2582,6 +3159,34 @@ export declare function readRows(root: ParentNode, selector: string): readonly s
|
|
|
2582
3159
|
*/
|
|
2583
3160
|
export declare function readRules(): readonly CSSRule[];
|
|
2584
3161
|
|
|
3162
|
+
/**
|
|
3163
|
+
* Reads one painted pixel of an element's screenshot.
|
|
3164
|
+
*
|
|
3165
|
+
* @param element - The rendered element to shoot.
|
|
3166
|
+
* @param x - The pixel's horizontal position as a fraction of the shot's width, from `0` to `1`.
|
|
3167
|
+
* @param y - The pixel's vertical position as a fraction of the shot's height, from `0` to `1`.
|
|
3168
|
+
* @returns The pixel's frozen color: its channels from 0 to 255 and its alpha from 0 to 1.
|
|
3169
|
+
* @throws Thrown when either position is not a finite fraction from `0` to `1`, when the provider
|
|
3170
|
+
* cannot shoot the element, when the shot is not an image this browser decodes, and when the browser
|
|
3171
|
+
* hands out no 2D canvas to measure it on.
|
|
3172
|
+
*
|
|
3173
|
+
* @remarks
|
|
3174
|
+
* The runner scales the tester to fit its window, so a shot's size in device pixels is not the
|
|
3175
|
+
* element's size in CSS pixels. The position is therefore a fraction of the shot rather than an
|
|
3176
|
+
* offset, and a fraction of `1` reads the last row or column rather than one past it. A position
|
|
3177
|
+
* that is `NaN`, infinite, or outside `0` to `1` is refused before the shot is taken, because it
|
|
3178
|
+
* would read outside the shot as a transparent black nothing painted, or coerce to an edge. The
|
|
3179
|
+
* decode and the canvas come from {@link paintImage}, which {@link readFrame} reads through as well.
|
|
3180
|
+
* The shot is not saved. The reading is what the provider painted, so it answers for compositing, stacking, and
|
|
3181
|
+
* clipping that a computed style cannot see; it composes with `matchesColor` and `measureContrast`.
|
|
3182
|
+
*
|
|
3183
|
+
* @example
|
|
3184
|
+
* ```ts
|
|
3185
|
+
* const [red, green, blue] = await readShotPixel(figure, 0.5, 0.5)
|
|
3186
|
+
* ```
|
|
3187
|
+
*/
|
|
3188
|
+
export declare function readShotPixel(element: Element, x: number, y: number): Promise<Color>;
|
|
3189
|
+
|
|
2585
3190
|
/**
|
|
2586
3191
|
* Reads the states one element is announced in.
|
|
2587
3192
|
*
|
|
@@ -2702,6 +3307,14 @@ export declare function readValue(role: string, name: string): string;
|
|
|
2702
3307
|
* waits per axis for the recorded value, and removes the marker after every axis agrees. With no
|
|
2703
3308
|
* marker, sends the empty reset and compares readings taken strictly after that send. Each poll
|
|
2704
3309
|
* waits for a frame; the interval is 10 milliseconds. The provider must expose a DevTools session.
|
|
3310
|
+
* A fifth marker bit restores pointer precision through touch emulation. A four-bit marker or an
|
|
3311
|
+
* unstaged release leaves touch emulation alone. Restoring coarse precision uses one touch point;
|
|
3312
|
+
* the marker does not preserve a provider's earlier maximum touch-point count.
|
|
3313
|
+
* {@link releaseTouch} leaves this marker intact even when it disables a staged coarse pointer,
|
|
3314
|
+
* so media release still restores the reading recorded before the first pointer stage.
|
|
3315
|
+
* A first pointer stage while {@link tapTouch} emulation is live records coarse. In teardown,
|
|
3316
|
+
* call this release before {@link releaseTouch}; reversing the order restores coarse emulation
|
|
3317
|
+
* after touch cleanup.
|
|
2705
3318
|
*
|
|
2706
3319
|
* @example
|
|
2707
3320
|
* ```ts
|
|
@@ -2752,8 +3365,9 @@ export declare function releasePane(): Promise<void>;
|
|
|
2752
3365
|
* to its park point in cleanup, and a rejection there joins the aggregate described under `@throws`.
|
|
2753
3366
|
* The provider must expose a DevTools session.
|
|
2754
3367
|
*
|
|
2755
|
-
* The
|
|
2756
|
-
*
|
|
3368
|
+
* The pointer parks through the `parkPointer` verb, which sends no release of its own. The park
|
|
3369
|
+
* point is (-1, -1) in the runner page's coordinates, one pixel above and to the left of that
|
|
3370
|
+
* page's viewport. The browser hit-tests nothing outside the viewport, so no element takes a
|
|
2757
3371
|
* `mouseover` event or hover paint from the parked pointer until the next pointer verb. This holds
|
|
2758
3372
|
* even where a staging, scroll, or offset lays content over the park point.
|
|
2759
3373
|
*
|
|
@@ -2764,6 +3378,30 @@ export declare function releasePane(): Promise<void>;
|
|
|
2764
3378
|
*/
|
|
2765
3379
|
export declare function releasePointer(): Promise<void>;
|
|
2766
3380
|
|
|
3381
|
+
/**
|
|
3382
|
+
* Cancels emulated touch input, disables touch emulation, and parks the pointer.
|
|
3383
|
+
*
|
|
3384
|
+
* @returns A promise resolving after touch cleanup and the parked pointer's frame.
|
|
3385
|
+
* @throws Thrown when a protocol command fails, apart from Chromium's idle touch cancellation refusal.
|
|
3386
|
+
*
|
|
3387
|
+
* @remarks
|
|
3388
|
+
* Safe after a completed tap, a held touch, or an idle release. This sends no mouse button release.
|
|
3389
|
+
* A native drag that also holds the mouse requires its own `mouseReleased` protocol command before
|
|
3390
|
+
* parking. {@link releasePointer} releases only a press recorded by the package's hold verbs.
|
|
3391
|
+
* Parking after touch input does not prove that Chromium cleared sticky touch hover.
|
|
3392
|
+
* Disables even a coarse pointer staged by {@link stageMedia}, leaving its restoration marker
|
|
3393
|
+
* unchanged. Stage the coarse pointer again when later steps need it; {@link releaseMedia} still
|
|
3394
|
+
* restores the pointer reading recorded before the first pointer stage.
|
|
3395
|
+
* If that stage ran while {@link tapTouch} emulation was live, it recorded coarse. In teardown,
|
|
3396
|
+
* call {@link releaseMedia} before this cleanup; reversing the order ends with coarse emulation.
|
|
3397
|
+
*
|
|
3398
|
+
* @example
|
|
3399
|
+
* ```ts
|
|
3400
|
+
* await releaseTouch()
|
|
3401
|
+
* ```
|
|
3402
|
+
*/
|
|
3403
|
+
export declare function releaseTouch(): Promise<void>;
|
|
3404
|
+
|
|
2767
3405
|
/**
|
|
2768
3406
|
* Deletes one IndexedDB database and reports what the request actually did.
|
|
2769
3407
|
*
|
|
@@ -2889,6 +3527,19 @@ export declare function resolveAccessible(role: string, name: string): HTMLEleme
|
|
|
2889
3527
|
*/
|
|
2890
3528
|
export declare function resolveAccessibleWithin(region: string, role: string, name: string): HTMLElement;
|
|
2891
3529
|
|
|
3530
|
+
/**
|
|
3531
|
+
* Resolves one visible, enabled, focus-reachable native file input by its exact label.
|
|
3532
|
+
*
|
|
3533
|
+
* @param name - The input's accessible label.
|
|
3534
|
+
* @returns The unique reachable native file input.
|
|
3535
|
+
* @throws When the label is absent, ambiguous, hidden, disabled, or outside the active modal.
|
|
3536
|
+
* @example
|
|
3537
|
+
* ```ts
|
|
3538
|
+
* resolveFileInput('Attachments')
|
|
3539
|
+
* ```
|
|
3540
|
+
*/
|
|
3541
|
+
export declare function resolveFileInput(name: string): HTMLInputElement;
|
|
3542
|
+
|
|
2892
3543
|
/**
|
|
2893
3544
|
* Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
|
|
2894
3545
|
* viewport yet.
|
|
@@ -2918,29 +3569,151 @@ export declare function resolveAccessibleWithin(region: string, role: string, na
|
|
|
2918
3569
|
*/
|
|
2919
3570
|
export declare function resolveRendered(first: string, second?: string): HTMLElement;
|
|
2920
3571
|
|
|
3572
|
+
/**
|
|
3573
|
+
* Carries files from outside the page over a rendered target named by role and accessible name.
|
|
3574
|
+
*
|
|
3575
|
+
* @param type - The protocol drag event; cancellation leaves the target before ending the drag.
|
|
3576
|
+
* @param role - The target's accessible role.
|
|
3577
|
+
* @param name - The target's exact accessible name.
|
|
3578
|
+
* @param names - The file names to write under the provider root's `tmp/drag` directory.
|
|
3579
|
+
* @returns A promise resolving after the browser accepts the event.
|
|
3580
|
+
* @throws Thrown when the target is absent, ambiguous, or outside the viewport after scrolling,
|
|
3581
|
+
* a file name contains a path, or the provider refuses a file write or protocol command.
|
|
3582
|
+
*
|
|
3583
|
+
* @remarks
|
|
3584
|
+
* Resolves rendered elements through {@link isRendered}, without focus reachability. A status or
|
|
3585
|
+
* region can receive a drag without being a Tab stop. Events are trusted and carry the `Files`
|
|
3586
|
+
* type. No drop is sent. Chromium raises no `dragleave` for protocol cancellation alone, so
|
|
3587
|
+
* cancellation first moves the drag outside the page.
|
|
3588
|
+
*
|
|
3589
|
+
* @example
|
|
3590
|
+
* ```ts
|
|
3591
|
+
* await sendFileDrag('dragEnter', 'status', 'Drop status', ['note.txt'])
|
|
3592
|
+
* await sendFileDrag('dragCancel', 'status', 'Drop status', ['note.txt'])
|
|
3593
|
+
* ```
|
|
3594
|
+
*/
|
|
3595
|
+
export declare function sendFileDrag(type: 'dragEnter' | 'dragOver' | 'dragCancel', role: string, name: string, names: readonly string[]): Promise<void>;
|
|
3596
|
+
|
|
2921
3597
|
/**
|
|
2922
3598
|
* Sends one DevTools protocol command through the browser provider.
|
|
2923
3599
|
*
|
|
2924
3600
|
* @param method - The protocol method name.
|
|
2925
|
-
* @param params - The protocol parameters.
|
|
2926
|
-
* @returns A promise resolving
|
|
3601
|
+
* @param params - The protocol parameters. Omit them for a command that takes none.
|
|
3602
|
+
* @returns A promise resolving to the browser's reply once the command completes.
|
|
2927
3603
|
* @throws Thrown when the provider exposes no DevTools session, or the command fails.
|
|
2928
3604
|
*
|
|
3605
|
+
* @remarks
|
|
3606
|
+
* The reply is typed `unknown`, because its shape is the command's and the provider's types stay out
|
|
3607
|
+
* of a browser file. Narrow it with guards before reading a field.
|
|
3608
|
+
*
|
|
2929
3609
|
* @example
|
|
2930
3610
|
* ```ts
|
|
2931
3611
|
* await sendProtocol('Emulation.setEmulatedMedia', { media: '', features: [] })
|
|
2932
3612
|
* ```
|
|
2933
3613
|
*/
|
|
2934
|
-
export declare function sendProtocol(method: string, params
|
|
3614
|
+
export declare function sendProtocol(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
|
|
2935
3615
|
|
|
2936
3616
|
/**
|
|
2937
|
-
*
|
|
2938
|
-
*
|
|
3617
|
+
* Sends one emulated touch event through the browser protocol.
|
|
3618
|
+
*
|
|
3619
|
+
* @param type - The Chrome DevTools Protocol touch event type.
|
|
3620
|
+
* @param element - The connected element locating the touch; omit it to end or cancel every point.
|
|
3621
|
+
* @param point - The offset from the element's top-left corner. Default: `{ x: 20, y: 20 }`.
|
|
3622
|
+
* @returns A promise resolving after the browser accepts the event.
|
|
3623
|
+
* @throws Thrown when the element is disconnected, the provider exposes no DevTools session, or the
|
|
3624
|
+
* browser refuses the touch sequence.
|
|
3625
|
+
*
|
|
3626
|
+
* @example
|
|
3627
|
+
* ```ts
|
|
3628
|
+
* await sendTouch('touchStart', target)
|
|
3629
|
+
* await sendTouch('touchEnd')
|
|
3630
|
+
* ```
|
|
3631
|
+
*/
|
|
3632
|
+
export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd' | 'touchCancel', element?: Element, point?: ProtocolPoint): Promise<void>;
|
|
3633
|
+
|
|
3634
|
+
/**
|
|
3635
|
+
* Settles the page for one capture: parks the pointer, waits out every finite animation, and holds
|
|
3636
|
+
* each endless animation at its first frame.
|
|
3637
|
+
*
|
|
3638
|
+
* @param options - The time bounds of the wait, its abort signal, and whether the pointer parks.
|
|
3639
|
+
* @returns A promise resolving, after one more frame has painted, to the resume: a function that
|
|
3640
|
+
* sets every held animation running again.
|
|
3641
|
+
* @throws Thrown when the pointer cannot park, as {@link parkPointer} raises it, and when a finite
|
|
3642
|
+
* animation is still running at the budget, as {@link waitForAnimations} raises it. An aborted wait
|
|
3643
|
+
* rejects with the signal's reason.
|
|
3644
|
+
*
|
|
3645
|
+
* @remarks
|
|
3646
|
+
* A pointer left over a control paints that control's hover, and a transition still running paints
|
|
3647
|
+
* a fill between two states, so neither is a state the interface rests in. An endless animation, a
|
|
3648
|
+
* spinner or a placeholder shimmer, stands at a different phase in every frame unless it is held at
|
|
3649
|
+
* the same one, so each is paused at its first frame. Call the resume once the frame is shot; a
|
|
3650
|
+
* capture that throws still owes it, so call it from a `finally` block.
|
|
3651
|
+
*
|
|
3652
|
+
* The subject is the whole document, its root element included. The pointer parks through
|
|
3653
|
+
* {@link parkPointer}, which sends no button release, so a held press stays held either way. Pass
|
|
3654
|
+
* `pointer: false` only where the pointer is part of the state, such as a drag in flight: the
|
|
3655
|
+
* control under it then keeps its hover and its pressed paint. Default budget: `1000` milliseconds.
|
|
3656
|
+
*
|
|
3657
|
+
* @example
|
|
3658
|
+
* ```ts
|
|
3659
|
+
* const resume = await settleCapture()
|
|
3660
|
+
* try {
|
|
3661
|
+
* await portfolio.place('start-empty')
|
|
3662
|
+
* } finally {
|
|
3663
|
+
* resume()
|
|
3664
|
+
* }
|
|
3665
|
+
* ```
|
|
3666
|
+
*/
|
|
3667
|
+
export declare function settleCapture(options?: SettleOptions): Promise<() => void>;
|
|
3668
|
+
|
|
3669
|
+
/**
|
|
3670
|
+
* Configures one capture settle: the time bounds of {@link WaitOptions} and whether the pointer
|
|
3671
|
+
* parks first.
|
|
3672
|
+
*
|
|
3673
|
+
* @remarks
|
|
3674
|
+
* The bounds go to the wait on finite animations and mean there what they mean everywhere else.
|
|
3675
|
+
* Leave the pointer where it is only where the pointer is part of the state being shot, such as a
|
|
3676
|
+
* drag in flight.
|
|
3677
|
+
*/
|
|
3678
|
+
export declare interface SettleOptions extends WaitOptions {
|
|
3679
|
+
/** Determines whether the pointer parks outside the page before the wait. Default: `true`. */
|
|
3680
|
+
readonly pointer?: boolean;
|
|
3681
|
+
}
|
|
3682
|
+
|
|
3683
|
+
/**
|
|
3684
|
+
* Describes an adopted stylesheet and its idempotent release operation.
|
|
3685
|
+
*/
|
|
3686
|
+
export declare interface SheetAdoption {
|
|
3687
|
+
/** Holds the stylesheet adopted into the document. */
|
|
3688
|
+
readonly sheet: CSSStyleSheet;
|
|
3689
|
+
/**
|
|
3690
|
+
* Removes this sheet from the document without removing another adoption.
|
|
3691
|
+
*
|
|
3692
|
+
* @returns Nothing.
|
|
3693
|
+
*/
|
|
3694
|
+
release(): void;
|
|
3695
|
+
}
|
|
3696
|
+
|
|
3697
|
+
/**
|
|
3698
|
+
* Configures how long a reading must hold still: the time bounds of {@link WaitOptions} and the
|
|
3699
|
+
* count of reads it must agree across.
|
|
3700
|
+
*/
|
|
3701
|
+
export declare interface StabilityOptions extends WaitOptions {
|
|
3702
|
+
/**
|
|
3703
|
+
* Holds the count of reads, each taken after a painted frame, that must repeat the settled
|
|
3704
|
+
* reading, so the last `frames + 1` reads agree. Default: `4`.
|
|
3705
|
+
*/
|
|
3706
|
+
readonly frames?: number;
|
|
3707
|
+
}
|
|
3708
|
+
|
|
3709
|
+
/**
|
|
3710
|
+
* Stages the tester's print medium, motion preference, forced colours, and pointer precision through
|
|
3711
|
+
* the browser provider.
|
|
2939
3712
|
*
|
|
2940
3713
|
* @param options - The media axes to override.
|
|
2941
3714
|
* @returns A promise resolving after a bounded read-back for `print: true`, either `motion` value,
|
|
2942
|
-
* and either `
|
|
2943
|
-
* read-back.
|
|
3715
|
+
* either `forced` value, and either `pointer` value. A `print: false` stage is sent and followed by
|
|
3716
|
+
* a frame wait without a read-back.
|
|
2944
3717
|
* @throws Thrown when no axis is supplied or a staged query does not reach the tester.
|
|
2945
3718
|
*
|
|
2946
3719
|
* @remarks
|
|
@@ -2953,6 +3726,14 @@ export declare function sendProtocol(method: string, params: Readonly<Record<str
|
|
|
2953
3726
|
* budgets. A restoration failure is attached as the refusal's cause. Register
|
|
2954
3727
|
* {@link releaseMedia} in teardown; it restores the readings observed before the first stage.
|
|
2955
3728
|
*
|
|
3729
|
+
* A coarse pointer enables single-point touch emulation; a fine pointer disables it. Chromium also
|
|
3730
|
+
* changes `any-pointer` and the hover queries. An omitted pointer never sends a touch-emulation
|
|
3731
|
+
* command. The first pointer stage appends its pre-call coarse reading to the media marker.
|
|
3732
|
+
* {@link releaseTouch} disables a staged coarse pointer without changing that marker. Stage the
|
|
3733
|
+
* pointer again after touch cleanup when later steps need coarse precision.
|
|
3734
|
+
* A first pointer stage while {@link tapTouch} emulation is live records coarse. In teardown,
|
|
3735
|
+
* call {@link releaseMedia} before {@link releaseTouch}; reversing the order ends coarse.
|
|
3736
|
+
*
|
|
2956
3737
|
* @example
|
|
2957
3738
|
* ```ts
|
|
2958
3739
|
* await stageMedia({ motion: false, print: true })
|
|
@@ -3025,6 +3806,30 @@ export declare interface StateOptions extends WaitOptions {
|
|
|
3025
3806
|
readonly absent?: boolean;
|
|
3026
3807
|
}
|
|
3027
3808
|
|
|
3809
|
+
/**
|
|
3810
|
+
* Presses Tab and yields the element focus lands on, once per press, up to a limit.
|
|
3811
|
+
*
|
|
3812
|
+
* @param limit - The most presses to make.
|
|
3813
|
+
* @returns An async generator of the element each press landed on, `undefined` where only a body, a
|
|
3814
|
+
* non-HTML element, or nothing took focus.
|
|
3815
|
+
* @throws Thrown when a press rejects, or focus lands in a frame from another origin.
|
|
3816
|
+
*
|
|
3817
|
+
* @remarks
|
|
3818
|
+
* This is the one Tab loop {@link driveTraversal} and {@link walkFocus} share. It makes a real press
|
|
3819
|
+
* through the provider, reads the landing with {@link readActiveElement}, and leaves every decision
|
|
3820
|
+
* to the caller: what counts as an end, a revisit, or a stop is the consumer's, because the two
|
|
3821
|
+
* consumers disagree. The press is the next one only after the consumer asks for the next landing, so
|
|
3822
|
+
* a consumer that stops reading stops pressing.
|
|
3823
|
+
*
|
|
3824
|
+
* @example
|
|
3825
|
+
* ```ts
|
|
3826
|
+
* for await (const focused of stepFocus(10)) {
|
|
3827
|
+
* if (focused?.id === 'save') break
|
|
3828
|
+
* }
|
|
3829
|
+
* ```
|
|
3830
|
+
*/
|
|
3831
|
+
export declare function stepFocus(limit: number): AsyncGenerator<HTMLElement | undefined, void, undefined>;
|
|
3832
|
+
|
|
3028
3833
|
/**
|
|
3029
3834
|
* Configures an inert `Storage`: its seed, which operations the host permits, and its quota.
|
|
3030
3835
|
*
|
|
@@ -3048,6 +3853,32 @@ export declare interface StorageOptions {
|
|
|
3048
3853
|
readonly quota?: number;
|
|
3049
3854
|
}
|
|
3050
3855
|
|
|
3856
|
+
/**
|
|
3857
|
+
* Taps an element's centre with emulated touch after its box settles.
|
|
3858
|
+
*
|
|
3859
|
+
* @param element - The connected element locating the tap.
|
|
3860
|
+
* @param options - The stability frame count, time bounds, and abort signal.
|
|
3861
|
+
* @returns A promise resolving after the browser accepts the touch end.
|
|
3862
|
+
* @throws Thrown when stability fails, the element is disconnected, or a protocol command fails.
|
|
3863
|
+
*
|
|
3864
|
+
* @remarks
|
|
3865
|
+
* Uses one touch point and leaves touch emulation enabled until {@link releaseTouch}.
|
|
3866
|
+
* That cleanup disables even a coarse pointer staged by {@link stageMedia}; stage it again after
|
|
3867
|
+
* cleanup when later steps need coarse precision.
|
|
3868
|
+
* A first pointer stage while tap emulation is live records coarse as its pre-call reading.
|
|
3869
|
+
* In teardown, call {@link releaseMedia} before {@link releaseTouch}; reversing that order restores
|
|
3870
|
+
* coarse emulation after touch cleanup.
|
|
3871
|
+
* The wait uses {@link waitForStability}; an unsettled scroller can consume a tap to stop momentum
|
|
3872
|
+
* without producing a click. No scrolling or focus-reachability check is performed.
|
|
3873
|
+
*
|
|
3874
|
+
* @example
|
|
3875
|
+
* ```ts
|
|
3876
|
+
* await tapTouch(target, { budget: 2000 })
|
|
3877
|
+
* await releaseTouch()
|
|
3878
|
+
* ```
|
|
3879
|
+
*/
|
|
3880
|
+
export declare function tapTouch(element: Element, options?: StabilityOptions): Promise<void>;
|
|
3881
|
+
|
|
3051
3882
|
/**
|
|
3052
3883
|
* Reaches a named control only through natural forward Tab traversal from the current focus.
|
|
3053
3884
|
*
|
|
@@ -3178,6 +4009,38 @@ export declare function waitForAnimations(element: Element, options?: WaitOption
|
|
|
3178
4009
|
*/
|
|
3179
4010
|
export declare function waitForFrame(): Promise<void>;
|
|
3180
4011
|
|
|
4012
|
+
/**
|
|
4013
|
+
* Waits for a reading to hold across its last `frames + 1` reads, each later read taken after a
|
|
4014
|
+
* painted frame, with the interval slept between polls. Checks the budget between reads, so a frame
|
|
4015
|
+
* that never paints is not bounded by it.
|
|
4016
|
+
*
|
|
4017
|
+
* @param description - The wait described in a timeout error.
|
|
4018
|
+
* @param read - The reading to compare from read to read, such as a scroll position or a box.
|
|
4019
|
+
* @param options - The frame count, the time bounds, and the abort signal.
|
|
4020
|
+
* @returns A promise resolving after the last `frames + 1` reads agree.
|
|
4021
|
+
* @throws Thrown when the frame count is not a positive integer, when `read` throws, or when the
|
|
4022
|
+
* reading keeps changing until the budget runs out. The timeout error names the description.
|
|
4023
|
+
*
|
|
4024
|
+
* @remarks
|
|
4025
|
+
* The first read is immediate. Each later read follows one painted frame, and every later read but
|
|
4026
|
+
* the first also follows the interval, which `waitForCondition` sleeps between polls. The reads are
|
|
4027
|
+
* therefore not on consecutive frames: an interval longer than a frame skips the frames in between.
|
|
4028
|
+
* The wait ends when the last `frames + 1` reads agree, so a reading that settles on read `n`
|
|
4029
|
+
* resolves on read `n + frames`.
|
|
4030
|
+
*
|
|
4031
|
+
* The abort signal is checked between reads too, so neither the budget nor the signal ends a wait
|
|
4032
|
+
* parked on a frame that never paints. Default frames: `4`. Default budget: `1000` milliseconds.
|
|
4033
|
+
* Default interval: `10` milliseconds.
|
|
4034
|
+
*
|
|
4035
|
+
* @example
|
|
4036
|
+
* ```ts
|
|
4037
|
+
* await waitForStability('the panel holds its box', () =>
|
|
4038
|
+
* JSON.stringify(panel.getBoundingClientRect().toJSON()),
|
|
4039
|
+
* )
|
|
4040
|
+
* ```
|
|
4041
|
+
*/
|
|
4042
|
+
export declare function waitForStability(description: string, read: () => string, options?: StabilityOptions): Promise<void>;
|
|
4043
|
+
|
|
3181
4044
|
/**
|
|
3182
4045
|
* Waits until one named control announces a state, or stops announcing it.
|
|
3183
4046
|
*
|
|
@@ -3231,6 +4094,35 @@ export declare function waitForState(name: string, state: string, options?: Stat
|
|
|
3231
4094
|
*/
|
|
3232
4095
|
export declare function waitForState(role: string, name: string, state: string, options?: StateOptions): Promise<readonly string[]>;
|
|
3233
4096
|
|
|
4097
|
+
/**
|
|
4098
|
+
* Walks forward by real Tab presses from the focused element until a predicate accepts a stop or
|
|
4099
|
+
* the Tab order ends.
|
|
4100
|
+
*
|
|
4101
|
+
* @param stop - Accepts the destination. Omit it to census the remaining document.
|
|
4102
|
+
* @returns Every element focus reached, in order and each once, the accepted stop last.
|
|
4103
|
+
* @throws Thrown when the walk outlasts every element the page holds, a key press rejects, or focus
|
|
4104
|
+
* lands in a frame from another origin.
|
|
4105
|
+
*
|
|
4106
|
+
* @remarks
|
|
4107
|
+
* The walk records the focused element and then presses Tab through {@link stepFocus}, so it reaches
|
|
4108
|
+
* what the browser's own sequential navigation reaches, including a scroll container Chromium
|
|
4109
|
+
* focuses without a `tabindex`. The static {@link describeFocus} sort does not. Each stop is the
|
|
4110
|
+
* innermost focused element {@link readActiveElement} reads, so a control inside an open shadow root
|
|
4111
|
+
* or a same-origin frame is a stop of its own, and its host or frame element is not. The walk ends
|
|
4112
|
+
* with an empty list when only the body holds focus, and where focus revisits a stop or returns to
|
|
4113
|
+
* the body. It applies no rule about which stop counts: the predicate sees each one and decides, so
|
|
4114
|
+
* a consumer that refuses a hidden stop throws from its own predicate.
|
|
4115
|
+
*
|
|
4116
|
+
* A closed shadow root cannot be entered, so its host stands for everything inside it, and a frame
|
|
4117
|
+
* from another origin is refused because its controls cannot be named.
|
|
4118
|
+
*
|
|
4119
|
+
* @example
|
|
4120
|
+
* ```ts
|
|
4121
|
+
* const stops = await walkFocus((focused) => focused.id === 'save')
|
|
4122
|
+
* ```
|
|
4123
|
+
*/
|
|
4124
|
+
export declare function walkFocus(stop?: (element: HTMLElement) => boolean): Promise<readonly HTMLElement[]>;
|
|
4125
|
+
|
|
3234
4126
|
/**
|
|
3235
4127
|
* Holds a store the host can withhold and later grant.
|
|
3236
4128
|
*
|