@orkestrel/test 0.0.20 → 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
  *
@@ -1633,11 +1658,21 @@ export declare function matchesColor(first: string | Color, second: string | Col
1633
1658
  * against the viewport answers what that viewport actually laid out.
1634
1659
  *
1635
1660
  * Each element contributes its client rectangle's bottom edge in document coordinates plus its own
1636
- * bottom margin, which sits outside that rectangle, and the largest contribution wins. Taking the
1637
- * largest is what handles a collapsed margin without asking whether it collapsed: a child margin
1638
- * that collapses out through its parent is counted once, at the child, and one the parent's padding
1639
- * holds in is counted once, at the parent. The body's and the root's own bottom padding and margin
1640
- * 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.
1641
1676
  *
1642
1677
  * The sum is rounded up because a box can end part way through a row and a frame cannot hold part
1643
1678
  * of one.
@@ -1974,6 +2009,58 @@ export declare function readCensus(root: ParentNode): CensusReading;
1974
2009
  */
1975
2010
  export declare function readClasses(root: ParentNode): ReadonlySet<string>;
1976
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
+
1977
2064
  /**
1978
2065
  * Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
1979
2066
  *
@@ -2530,6 +2530,97 @@ function readPixels(element, property, pseudo) {
2530
2530
  return Number.isFinite(measured) ? measured : 0;
2531
2531
  }
2532
2532
  /**
2533
+ * Measures the row a clipping element cuts its content off at, in document coordinates.
2534
+ *
2535
+ * @param element - The element to read.
2536
+ * @returns The element's overflow clip edge in CSS pixels from the document's top, or the
2537
+ * `undefined` value for an element that clips nothing, as the {@link clipsOverflow} helper reports
2538
+ * it.
2539
+ *
2540
+ * @remarks
2541
+ * An `overflow-y` value of the `hidden` keyword, the `auto` keyword, or the `scroll` keyword stops
2542
+ * the content at the padding box, whatever the element's `overflow-clip-margin` value says. A
2543
+ * `clip` overflow and a paint containment over a `visible` overflow start the edge from the box the
2544
+ * computed `overflow-clip-margin` value names (the `border-box` keyword, the `padding-box` keyword,
2545
+ * or the `content-box` keyword, and the padding box where the value names none) and expand it by
2546
+ * the length the {@link readClipMargin} helper reads. So a bordered or padded frame whose clip
2547
+ * margin names no box ends at its padding box plus the margin, where the browser stops painting its
2548
+ * content, rather than at its border box plus the margin. The computed value drops the
2549
+ * `padding-box` keyword because it is the default, which is why a value carrying no keyword reads
2550
+ * from the padding box.
2551
+ *
2552
+ * The edge is the bottom one, because that is the edge a reading of the document's height meets.
2553
+ *
2554
+ * @example
2555
+ * ```ts
2556
+ * const edge = readClipEdge(frame)
2557
+ * if (edge !== undefined && edge < bottom) bottom = edge
2558
+ * ```
2559
+ */
2560
+ function readClipEdge(element) {
2561
+ if (!clipsOverflow(element)) return void 0;
2562
+ const border = element.getBoundingClientRect().bottom + window.scrollY;
2563
+ const padding = border - readPixels(element, "border-bottom-width");
2564
+ const overflow = readStyle(element, "overflow-y");
2565
+ if (overflow !== "clip" && overflow !== "visible") return padding;
2566
+ const margin = readStyle(element, "overflow-clip-margin");
2567
+ if (margin.includes("border-box")) return border + readClipMargin(element);
2568
+ if (margin.includes("content-box")) return padding - readPixels(element, "padding-bottom") + readClipMargin(element);
2569
+ return padding + readClipMargin(element);
2570
+ }
2571
+ /**
2572
+ * Measures how far past its own box a clipping element lets its content show.
2573
+ *
2574
+ * @param element - The element to read.
2575
+ * @returns The computed `overflow-clip-margin` length in CSS pixels where the element's computed
2576
+ * `overflow-y` value is the `clip` keyword or its clip comes from paint containment alone, and zero
2577
+ * for every other element.
2578
+ *
2579
+ * @remarks
2580
+ * The `overflow-clip-margin` property expands the clip edge of a `clip` overflow and of a paint
2581
+ * containment over a `visible` overflow and has no effect on an `overflow-y` value of the `hidden`
2582
+ * keyword, the `auto` keyword, or the `scroll` keyword, whose content stops at the padding box
2583
+ * whatever the property says. The computed value can carry a visual-box keyword beside the length,
2584
+ * so the length is read wherever it sits in the value.
2585
+ *
2586
+ * @example
2587
+ * ```ts
2588
+ * readClipMargin(build('div', { attributes: { style: 'overflow: clip; overflow-clip-margin: 20px' } })) // 20
2589
+ * ```
2590
+ */
2591
+ function readClipMargin(element) {
2592
+ const overflow = readStyle(element, "overflow-y");
2593
+ if (overflow !== "clip" && !(overflow === "visible" && clipsOverflow(element))) return 0;
2594
+ const length = /(-?\d*\.?\d+)px/u.exec(readStyle(element, "overflow-clip-margin"));
2595
+ return length === null ? 0 : Number.parseFloat(length[1] ?? "0");
2596
+ }
2597
+ /**
2598
+ * Reports whether an element clips its descendants' overflow.
2599
+ *
2600
+ * @param element - The element to read.
2601
+ * @returns True if the element's computed `overflow-y` value is other than the `visible` keyword or
2602
+ * its computed `contain` value carries paint containment (the `paint` keyword, the `content`
2603
+ * keyword, or the `strict` keyword); false otherwise.
2604
+ *
2605
+ * @remarks
2606
+ * A scroll container (the `auto` keyword or the `scroll` keyword) keeps what overflows inside its
2607
+ * own scrollable area, and a clipping one (the `hidden` keyword or the `clip` keyword) and a
2608
+ * paint-contained one discard it, so in every case the rows a descendant lays out past the
2609
+ * element's clip edge, which the {@link readClipEdge} helper measures, are no part of the
2610
+ * document's content edge. The vertical axis alone decides, because the `overflow-x` property and
2611
+ * the `overflow-y` property compute independently under the `clip` keyword, and a horizontal clip
2612
+ * ends nothing below the element.
2613
+ *
2614
+ * @example
2615
+ * ```ts
2616
+ * clipsOverflow(build('div', { attributes: { style: 'overflow: clip' } })) // true
2617
+ * clipsOverflow(build('div')) // false
2618
+ * ```
2619
+ */
2620
+ function clipsOverflow(element) {
2621
+ return readStyle(element, "overflow-y") !== "visible" || /\b(?:paint|content|strict)\b/u.test(readStyle(element, "contain"));
2622
+ }
2623
+ /**
2533
2624
  * Measures the row the document's own content ends on, in document coordinates.
2534
2625
  *
2535
2626
  * @returns The content edge, rounded up to a whole row.
@@ -2545,11 +2636,21 @@ function readPixels(element, property, pseudo) {
2545
2636
  * against the viewport answers what that viewport actually laid out.
2546
2637
  *
2547
2638
  * Each element contributes its client rectangle's bottom edge in document coordinates plus its own
2548
- * bottom margin, which sits outside that rectangle, and the largest contribution wins. Taking the
2549
- * largest is what handles a collapsed margin without asking whether it collapsed: a child margin
2550
- * that collapses out through its parent is counted once, at the child, and one the parent's padding
2551
- * holds in is counted once, at the parent. The body's and the root's own bottom padding and margin
2552
- * sit under every child rather than beside them, so they are added after the walk.
2639
+ * bottom margin, which sits outside that rectangle, and the largest contribution wins. An ancestor
2640
+ * that clips its overflow caps the contribution at that ancestor's clip edge, which the
2641
+ * {@link readClipEdge} helper measures, because the rows a descendant lays out past a clipping
2642
+ * frame are cut, scrolled, or discarded rather than added to the document: a viewport-height
2643
+ * specimen inside a bounded frame ends, for this reading, where the frame ends, so a taller pane
2644
+ * does not read back as a taller document. The clip edge of a `clip` overflow, and of a paint
2645
+ * containment over a `visible` overflow, is read from the box the frame's `overflow-clip-margin`
2646
+ * value selects, the padding box by default, and expanded by that value's length; a hidden or
2647
+ * scrolling frame stops at its padding box. The frame's own contribution stays its border-box
2648
+ * bottom plus its bottom margin, so a bordered frame still ends the reading under its border.
2649
+ * Taking the largest is what handles a collapsed margin without asking whether it collapsed: a
2650
+ * child margin that collapses out through its parent is counted once, at the child, and one the
2651
+ * parent's padding holds in is counted once, at the parent. The body's and the root's own bottom
2652
+ * padding and margin sit under every child rather than beside them, so they are added after the
2653
+ * walk.
2553
2654
  *
2554
2655
  * The sum is rounded up because a box can end part way through a row and a frame cannot hold part
2555
2656
  * of one.
@@ -2562,7 +2663,11 @@ function readPixels(element, property, pseudo) {
2562
2663
  function measureContent() {
2563
2664
  let edge = 0;
2564
2665
  for (const element of document.body.querySelectorAll("*")) {
2565
- const bottom = element.getBoundingClientRect().bottom + window.scrollY + readPixels(element, "margin-bottom");
2666
+ let bottom = element.getBoundingClientRect().bottom + window.scrollY + readPixels(element, "margin-bottom");
2667
+ for (let frame = element.parentElement; frame !== null && frame !== document.body; frame = frame.parentElement) {
2668
+ const limit = readClipEdge(frame);
2669
+ if (limit !== void 0 && limit < bottom) bottom = limit;
2670
+ }
2566
2671
  if (bottom > edge) edge = bottom;
2567
2672
  }
2568
2673
  return Math.ceil(edge + readPixels(document.body, "padding-bottom") + readPixels(document.body, "margin-bottom") + readPixels(document.documentElement, "padding-bottom") + readPixels(document.documentElement, "margin-bottom"));
@@ -3667,6 +3772,6 @@ function createHarness(options) {
3667
3772
  };
3668
3773
  }
3669
3774
  //#endregion
3670
- export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, createChannel, createDragEvent, createHarness, createJournal, createPointerEvent, createPortfolio, createStorage, describeFocus, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readCensus, readClasses, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveRendered, sendProtocol, stageMedia, stagePane, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForState };
3775
+ export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, clipsOverflow, commitInput, computeNamePattern, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, createChannel, createDragEvent, createHarness, createJournal, createPointerEvent, createPortfolio, createStorage, describeFocus, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readCensus, readClasses, readClipEdge, readClipMargin, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveRendered, sendProtocol, stageMedia, stagePane, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForState };
3671
3776
 
3672
3777
  //# sourceMappingURL=index.js.map