@orkestrel/test 0.0.19 → 0.0.21

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.
@@ -421,6 +421,31 @@ export declare function clickAccessibleWithin(region: string, role: string, name
421
421
  */
422
422
  export declare function clickDisclosure(name: string): Promise<void>;
423
423
 
424
+ /**
425
+ * Reports whether an element clips its descendants' overflow.
426
+ *
427
+ * @param element - The element to read.
428
+ * @returns True if the element's computed `overflow-y` value is other than the `visible` keyword or
429
+ * its computed `contain` value carries paint containment (the `paint` keyword, the `content`
430
+ * keyword, or the `strict` keyword); false otherwise.
431
+ *
432
+ * @remarks
433
+ * A scroll container (the `auto` keyword or the `scroll` keyword) keeps what overflows inside its
434
+ * own scrollable area, and a clipping one (the `hidden` keyword or the `clip` keyword) and a
435
+ * paint-contained one discard it, so in every case the rows a descendant lays out past the
436
+ * element's clip edge, which the {@link readClipEdge} helper measures, are no part of the
437
+ * document's content edge. The vertical axis alone decides, because the `overflow-x` property and
438
+ * the `overflow-y` property compute independently under the `clip` keyword, and a horizontal clip
439
+ * ends nothing below the element.
440
+ *
441
+ * @example
442
+ * ```ts
443
+ * clipsOverflow(build('div', { attributes: { style: 'overflow: clip' } })) // true
444
+ * clipsOverflow(build('div')) // false
445
+ * ```
446
+ */
447
+ export declare function clipsOverflow(element: Element): boolean;
448
+
424
449
  /**
425
450
  * Represents one rendered color as straight sRGB channels and its alpha.
426
451
  *
@@ -975,6 +1000,54 @@ export declare function describeFocus(element: Element): string;
975
1000
  */
976
1001
  export declare function describeTree(element: Element): string;
977
1002
 
1003
+ /**
1004
+ * Holds the primary pointer button on the control a resolver returns, through the browser provider.
1005
+ *
1006
+ * @param resolve - The resolver that returns the target, called after the held-pointer refusal.
1007
+ * @param name - The target's name, as the refusals voice it.
1008
+ * @returns A promise resolving after the control enters its pressed state.
1009
+ * @throws Thrown when a pointer is already held, the resolver refuses, the target stays outside
1010
+ * the viewport after scrolling, or the press misses. A missed press that also fails to release
1011
+ * carries the release rejection as its cause.
1012
+ *
1013
+ * @remarks
1014
+ * This is the one pointer drive every hold verb shares: the held-marker refusal, a scroll that
1015
+ * brings a wholly off-viewport target into view and a refusal for one that stays outside, the
1016
+ * centre mapped through the tester iframe's painted scale into page coordinates, the trusted move
1017
+ * and press, the marker, a frame wait, and the `:active` read-back that releases before refusing a
1018
+ * missed press. The refusal precedes resolution, so a double hold is refused before an absent
1019
+ * name is.
1020
+ *
1021
+ * @example
1022
+ * ```ts
1023
+ * await driveHold(() => resolveAccessible('Apply'), 'Apply')
1024
+ * await releasePointer()
1025
+ * ```
1026
+ */
1027
+ export declare function driveHold(resolve: () => HTMLElement, name: string): Promise<void>;
1028
+
1029
+ /**
1030
+ * Reaches the control a resolver returns, only through natural forward Tab traversal from the
1031
+ * current focus.
1032
+ *
1033
+ * @param resolve - The resolver that returns the target, called before the first step and again on
1034
+ * every step, because a framework may replace the node between resolution and focus arrival.
1035
+ * @param name - The target's name, as the refusal voices it.
1036
+ * @returns The target after the browser moves focus to it.
1037
+ * @throws When the resolver refuses, or one complete traversal cannot reach the target.
1038
+ *
1039
+ * @remarks
1040
+ * This is the one loop every traversal verb shares. A step counts only when focus lands on an
1041
+ * element, the traversal is over when focus revisits one, and the cap is counted off
1042
+ * {@link FOCUSABLE_SELECTOR}.
1043
+ *
1044
+ * @example
1045
+ * ```ts
1046
+ * await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
1047
+ * ```
1048
+ */
1049
+ export declare function driveTraversal(resolve: () => HTMLElement, name: string): Promise<HTMLElement>;
1050
+
978
1051
  /**
979
1052
  * Configures one built element: its class list, its text, and its attributes.
980
1053
  *
@@ -1292,7 +1365,7 @@ export declare const HEADER_ROLES: Readonly<Record<string, string>>;
1292
1365
  * reading verifies delivery. A missed press releases before refusing; if that release also
1293
1366
  * rejects, the refusal carries it as its cause. Register {@link releasePointer} in teardown
1294
1367
  * before holding; release can produce a click on the pressed control. A rejected button-down send
1295
- * leaves no hold marker.
1368
+ * leaves no hold marker. The hold itself is {@link driveHold}.
1296
1369
  *
1297
1370
  * @example
1298
1371
  * ```ts
@@ -1319,6 +1392,30 @@ export declare function holdAccessible(name: string): Promise<void>;
1319
1392
  */
1320
1393
  export declare function holdAccessible(role: string, name: string): Promise<void>;
1321
1394
 
1395
+ /**
1396
+ * Holds the primary pointer button on one control by role and accessible-name text inside a named
1397
+ * region.
1398
+ *
1399
+ * @param region - The containing region's exact accessible name.
1400
+ * @param role - The control's exact ARIA role.
1401
+ * @param name - The rendered accessible-name text that identifies the control in that region.
1402
+ * @returns A promise resolving after the control enters its pressed state.
1403
+ * @throws Thrown when a pointer is already held, the region refuses the target, or the press
1404
+ * misses. A missed press that also fails to release carries the release rejection as its cause.
1405
+ *
1406
+ * @remarks
1407
+ * The resolution is {@link resolveAccessibleWithin} and the hold is {@link driveHold}, so a twin
1408
+ * of the same name in another region is left alone. Register {@link releasePointer} in teardown
1409
+ * before holding.
1410
+ *
1411
+ * @example
1412
+ * ```ts
1413
+ * await holdAccessibleWithin('Ledger', 'button', 'Apply')
1414
+ * await releasePointer()
1415
+ * ```
1416
+ */
1417
+ export declare function holdAccessibleWithin(region: string, role: string, name: string): Promise<void>;
1418
+
1322
1419
  /**
1323
1420
  * Hovers one visible, focus-reachable control by its accessible name through the browser provider.
1324
1421
  *
@@ -1561,11 +1658,21 @@ export declare function matchesColor(first: string | Color, second: string | Col
1561
1658
  * against the viewport answers what that viewport actually laid out.
1562
1659
  *
1563
1660
  * Each element contributes its client rectangle's bottom edge in document coordinates plus its own
1564
- * bottom margin, which sits outside that rectangle, and the largest contribution wins. Taking the
1565
- * largest is what handles a collapsed margin without asking whether it collapsed: a child margin
1566
- * that collapses out through its parent is counted once, at the child, and one the parent's padding
1567
- * holds in is counted once, at the parent. The body's and the root's own bottom padding and margin
1568
- * sit under every child rather than beside them, so they are added after the walk.
1661
+ * bottom margin, which sits outside that rectangle, and the largest contribution wins. An ancestor
1662
+ * that clips its overflow caps the contribution at that ancestor's clip edge, which the
1663
+ * {@link readClipEdge} helper measures, because the rows a descendant lays out past a clipping
1664
+ * frame are cut, scrolled, or discarded rather than added to the document: a viewport-height
1665
+ * specimen inside a bounded frame ends, for this reading, where the frame ends, so a taller pane
1666
+ * does not read back as a taller document. The clip edge of a `clip` overflow, and of a paint
1667
+ * containment over a `visible` overflow, is read from the box the frame's `overflow-clip-margin`
1668
+ * value selects, the padding box by default, and expanded by that value's length; a hidden or
1669
+ * scrolling frame stops at its padding box. The frame's own contribution stays its border-box
1670
+ * bottom plus its bottom margin, so a bordered frame still ends the reading under its border.
1671
+ * Taking the largest is what handles a collapsed margin without asking whether it collapsed: a
1672
+ * child margin that collapses out through its parent is counted once, at the child, and one the
1673
+ * parent's padding holds in is counted once, at the parent. The body's and the root's own bottom
1674
+ * padding and margin sit under every child rather than beside them, so they are added after the
1675
+ * walk.
1569
1676
  *
1570
1677
  * The sum is rounded up because a box can end part way through a row and a frame cannot hold part
1571
1678
  * of one.
@@ -1617,12 +1724,14 @@ export declare function measureLuminance(color: Color): number;
1617
1724
  */
1618
1725
  export declare const MEDIA_STAGE = "data-media-stage";
1619
1726
 
1620
- /** Configures the tester's print medium and motion preference. */
1727
+ /** Configures the tester's print medium, motion preference, and forced colours. */
1621
1728
  export declare interface MediaOptions {
1622
1729
  /** Determines whether the tester lays out for print. Omit it to leave the medium alone. */
1623
1730
  readonly print?: boolean;
1624
1731
  /** Determines whether the tester prefers motion. Omit it to leave the preference alone. */
1625
1732
  readonly motion?: boolean;
1733
+ /** Determines whether the tester runs under forced colours. Omit it to leave the colours alone. */
1734
+ readonly forced?: boolean;
1626
1735
  }
1627
1736
 
1628
1737
  /**
@@ -1900,6 +2009,58 @@ export declare function readCensus(root: ParentNode): CensusReading;
1900
2009
  */
1901
2010
  export declare function readClasses(root: ParentNode): ReadonlySet<string>;
1902
2011
 
2012
+ /**
2013
+ * Measures the row a clipping element cuts its content off at, in document coordinates.
2014
+ *
2015
+ * @param element - The element to read.
2016
+ * @returns The element's overflow clip edge in CSS pixels from the document's top, or the
2017
+ * `undefined` value for an element that clips nothing, as the {@link clipsOverflow} helper reports
2018
+ * it.
2019
+ *
2020
+ * @remarks
2021
+ * An `overflow-y` value of the `hidden` keyword, the `auto` keyword, or the `scroll` keyword stops
2022
+ * the content at the padding box, whatever the element's `overflow-clip-margin` value says. A
2023
+ * `clip` overflow and a paint containment over a `visible` overflow start the edge from the box the
2024
+ * computed `overflow-clip-margin` value names (the `border-box` keyword, the `padding-box` keyword,
2025
+ * or the `content-box` keyword, and the padding box where the value names none) and expand it by
2026
+ * the length the {@link readClipMargin} helper reads. So a bordered or padded frame whose clip
2027
+ * margin names no box ends at its padding box plus the margin, where the browser stops painting its
2028
+ * content, rather than at its border box plus the margin. The computed value drops the
2029
+ * `padding-box` keyword because it is the default, which is why a value carrying no keyword reads
2030
+ * from the padding box.
2031
+ *
2032
+ * The edge is the bottom one, because that is the edge a reading of the document's height meets.
2033
+ *
2034
+ * @example
2035
+ * ```ts
2036
+ * const edge = readClipEdge(frame)
2037
+ * if (edge !== undefined && edge < bottom) bottom = edge
2038
+ * ```
2039
+ */
2040
+ export declare function readClipEdge(element: Element): number | undefined;
2041
+
2042
+ /**
2043
+ * Measures how far past its own box a clipping element lets its content show.
2044
+ *
2045
+ * @param element - The element to read.
2046
+ * @returns The computed `overflow-clip-margin` length in CSS pixels where the element's computed
2047
+ * `overflow-y` value is the `clip` keyword or its clip comes from paint containment alone, and zero
2048
+ * for every other element.
2049
+ *
2050
+ * @remarks
2051
+ * The `overflow-clip-margin` property expands the clip edge of a `clip` overflow and of a paint
2052
+ * containment over a `visible` overflow and has no effect on an `overflow-y` value of the `hidden`
2053
+ * keyword, the `auto` keyword, or the `scroll` keyword, whose content stops at the padding box
2054
+ * whatever the property says. The computed value can carry a visual-box keyword beside the length,
2055
+ * so the length is read wherever it sits in the value.
2056
+ *
2057
+ * @example
2058
+ * ```ts
2059
+ * readClipMargin(build('div', { attributes: { style: 'overflow: clip; overflow-clip-margin: 20px' } })) // 20
2060
+ * ```
2061
+ */
2062
+ export declare function readClipMargin(element: Element): number;
2063
+
1903
2064
  /**
1904
2065
  * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
1905
2066
  *
@@ -2618,6 +2779,28 @@ export declare function resolveAccessible(name: string): HTMLElement;
2618
2779
  */
2619
2780
  export declare function resolveAccessible(role: string, name: string): HTMLElement;
2620
2781
 
2782
+ /**
2783
+ * Resolves one human-reachable control by role and accessible-name text inside a named region.
2784
+ *
2785
+ * @param region - The containing region's exact accessible name.
2786
+ * @param role - The control's exact ARIA role.
2787
+ * @param name - The rendered accessible-name text that identifies the control in that region.
2788
+ * @returns The one reachable element carrying that role and name inside the region.
2789
+ * @throws When the named control is absent, unreachable, or ambiguous inside the region.
2790
+ *
2791
+ * @remarks
2792
+ * The region's name is matched exactly and the control's name loosely, over a computed name that
2793
+ * includes hidden subtrees, so a glyph joins the text rather than displacing it. One pass answers
2794
+ * this: a control the region cannot reach is refused whether it is absent or hidden. This is the
2795
+ * resolver the region-scoped verbs share.
2796
+ *
2797
+ * @example
2798
+ * ```ts
2799
+ * resolveAccessibleWithin('Ledger', 'button', 'Monthly income')
2800
+ * ```
2801
+ */
2802
+ export declare function resolveAccessibleWithin(region: string, role: string, name: string): HTMLElement;
2803
+
2621
2804
  /**
2622
2805
  * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
2623
2806
  * viewport yet.
@@ -2663,17 +2846,20 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
2663
2846
  export declare function sendProtocol(method: string, params: Readonly<Record<string, unknown>>): Promise<void>;
2664
2847
 
2665
2848
  /**
2666
- * Stages the tester's print medium and motion preference through the browser provider.
2849
+ * Stages the tester's print medium, motion preference, and forced colours through the browser
2850
+ * provider.
2667
2851
  *
2668
2852
  * @param options - The media axes to override.
2669
- * @returns A promise resolving after a bounded read-back for `print: true` and either
2670
- * `motion` value. A `print: false` stage is sent and followed by a frame wait without a read-back.
2853
+ * @returns A promise resolving after a bounded read-back for `print: true`, either `motion` value,
2854
+ * and either `forced` value. A `print: false` stage is sent and followed by a frame wait without a
2855
+ * read-back.
2671
2856
  * @throws Thrown when no axis is supplied or a staged query does not reach the tester.
2672
2857
  *
2673
2858
  * @remarks
2674
2859
  * If `print` is true, uses print; if false, uses screen. If `motion` is true, uses no preference;
2675
- * if false, uses reduced motion. The print medium, reduced motion, colour scheme, and forced colours
2676
- * keep their effective readings when omitted. Any other emulated feature the provider configured
2860
+ * if false, uses reduced motion. If `forced` is true, uses active forced colours; if false, uses
2861
+ * none. The print medium, reduced motion, colour scheme, and forced colours keep their effective
2862
+ * readings when omitted. Any other emulated feature the provider configured
2677
2863
  * is cleared. Each staged query waits up to 1000 milliseconds, polling every 10 milliseconds.
2678
2864
  * A refused read-back restores the carried pre-call readings before throwing and can take two
2679
2865
  * budgets. A restoration failure is attached as the refusal's cause. Register
@@ -2781,6 +2967,9 @@ export declare interface StorageOptions {
2781
2967
  * @returns The target after the browser moves focus to it.
2782
2968
  * @throws When one complete traversal cannot reach the target.
2783
2969
  *
2970
+ * @remarks
2971
+ * The loop is {@link driveTraversal} over {@link resolveRendered}.
2972
+ *
2784
2973
  * @example
2785
2974
  * ```ts
2786
2975
  * await traverseAccessible('Evaluate')
@@ -2788,6 +2977,27 @@ export declare interface StorageOptions {
2788
2977
  */
2789
2978
  export declare function traverseAccessible(name: string): Promise<HTMLElement>;
2790
2979
 
2980
+ /**
2981
+ * Reaches a control by role and accessible-name text inside a named region, only through natural
2982
+ * forward Tab traversal from the current focus.
2983
+ *
2984
+ * @param region - The containing region's exact accessible name.
2985
+ * @param role - The control's exact ARIA role.
2986
+ * @param name - The rendered accessible-name text that identifies the control in that region.
2987
+ * @returns The target after the browser moves focus to it.
2988
+ * @throws When the region refuses the target, or one complete traversal cannot reach it.
2989
+ *
2990
+ * @remarks
2991
+ * The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
2992
+ * twin of the same name earlier in the tab order is passed over rather than reached.
2993
+ *
2994
+ * @example
2995
+ * ```ts
2996
+ * await traverseAccessibleWithin('Ledger', 'button', 'Evaluate')
2997
+ * ```
2998
+ */
2999
+ export declare function traverseAccessibleWithin(region: string, role: string, name: string): Promise<HTMLElement>;
3000
+
2791
3001
  /**
2792
3002
  * Replaces a named field's value through focus, select-all, deletion, and real keystrokes.
2793
3003
  *