@orkestrel/test 0.0.34 → 0.0.36

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.
@@ -242,6 +242,28 @@ export declare function buildEscapes(permitted: string): EscapeFixture;
242
242
  */
243
243
  export declare const CANVAS_COLOR: RGBA;
244
244
 
245
+ /**
246
+ * Lists the form controls an unrolled frame leaves scrolled.
247
+ *
248
+ * @remarks
249
+ * A text area or a list box that overflows computes a scrolling overflow of its own, but its rows
250
+ * are the control's value rather than the page's layout, and no style the page could change would
251
+ * show them all. `collectUnrolledRegions` therefore leaves these elements out, so an unrolled frame
252
+ * neither grows for them nor refuses over them.
253
+ */
254
+ export declare const CAPTURE_CONTROLS: readonly string[];
255
+
256
+ /**
257
+ * Bounds the characters of the region locator a capture refusal names.
258
+ *
259
+ * @remarks
260
+ * `captureFrame` names each scroll region it leaves hiding rows by the path `renderSelector`
261
+ * renders. The path carries ids the page wrote, so it is cut to this many characters from its end,
262
+ * which keeps the steps nearest the region, and JSON-encoded, so a page-authored id can neither
263
+ * fake the message nor grow it without bound.
264
+ */
265
+ export declare const CAPTURE_LABEL_LIMIT = 120;
266
+
245
267
  /**
246
268
  * Names the attribute marking the runner's tester pane, and the rule that sizes it, while a frame
247
269
  * is staged.
@@ -278,8 +300,9 @@ export declare const CAPTURE_STAGE_LIMIT = 4;
278
300
  * @param options - The path to write, the viewport to shoot at, and the element to shoot.
279
301
  * @returns The absolute path of the written frame, after it has been read back and matched.
280
302
  * @throws Thrown when the pane cannot be staged, when the document's height or an element frame's
281
- * element height never settles under {@link CAPTURE_STAGE_LIMIT} restagings, when the provider wrote
282
- * the frame somewhere else, and when the bytes on disk are not the ones this shot produced.
303
+ * element height never settles under {@link CAPTURE_STAGE_LIMIT} restagings, when an unrolled frame
304
+ * leaves rows hidden in a scroll region, when the provider wrote the frame somewhere else, and when
305
+ * the bytes on disk are not the ones this shot produced.
283
306
  *
284
307
  * @remarks
285
308
  * The path a screenshot call returns is the path it meant to write, so it is not evidence a file
@@ -361,8 +384,39 @@ export declare const CAPTURE_STAGE_LIMIT = 4;
361
384
  *
362
385
  * The pane is staged for the frame and released before this returns, on the failing path as well as
363
386
  * the passing one, which hands the tester back the viewport it had before the first staging. The
364
- * tester's scroll position is restored after that release, on every path, a rejected release
365
- * included.
387
+ * tester's scroll position, and that of every scroll container {@link collectScrollContainers}
388
+ * finds, is recorded before the first staging and restored after that release, on every path, a
389
+ * rejected release included.
390
+ *
391
+ * Set the `unrolled` option to cover the rows each vertical scroll region hides. Every staging then
392
+ * adds the hidden rows of each region {@link collectUnrolledRegions} finds, overlapping the element
393
+ * for an element frame, to the edge it stages at, and the page's own layout grows a region bound to
394
+ * the viewport with the pane; nothing is written to the page's styles. Hidden rows add up, which is
395
+ * right for nested regions and too much for panes side by side, so after none of the regions that
396
+ * hid rows at the first reading hides rows, each staging moves down by the smallest slack among
397
+ * them, which {@link measureRegion} reads: a sidebar beside a taller main pane settles where the
398
+ * main pane's last row ends. A region whose height did not change across a staging keeps a fixed
399
+ * height, so its hidden rows stop counting and the staging settles without it. A layout that needs
400
+ * more restagings than {@link CAPTURE_STAGE_LIMIT} allows is refused with the never-settled
401
+ * refusal, which on an unrolled frame appends
402
+ * `; scroll regions still hiding rows: <region> hides <n> px, …` for every region still hiding rows.
403
+ *
404
+ * A region that still hides rows after the settling refuses the shot with
405
+ * `Capture frame at <path> leaves rows hidden in scroll regions: <region> <cause> and hides <n> px, so <correction>. Shoot the frame without unrolled to keep them scrolled`,
406
+ * naming every such region. The cause and correction come from what was measured: a region that
407
+ * kept its height across a staging, or kept the height it had at the declared viewport, `keeps a
408
+ * fixed height`, so bound its height to the viewport; a region whose height changed as the pane
409
+ * grew `grows by less than the pane`, so let it take all the height the pane adds; a region that
410
+ * hid no rows at the declared viewport hides them `at the final reading`, so let its height follow
411
+ * the viewport; and a region at a pane that never grew past the declared height hides its rows
412
+ * `though the declared viewport has room for them`, so let it fill the viewport's remaining height.
413
+ * Each region is named by the locator {@link renderLabel} renders.
414
+ *
415
+ * Three cases stay outside what an unrolled frame reads. A containing block that
416
+ * {@link containsFixed} does not read counts a fixed or absolute box as a row, which ends in the
417
+ * never-settled refusal naming the regions. A `:modal` dialog or a `:popover-open` element under a
418
+ * transformed ancestor is counted as a row, though the top layer lays it out. A region inside a
419
+ * closed shadow root is unreachable, so its rows stay hidden without a refusal.
366
420
  *
367
421
  * @example
368
422
  * ```ts
@@ -578,6 +632,91 @@ export declare function clipsOverflow(element: Element): boolean;
578
632
  */
579
633
  export declare function collectClippingAncestors(element: Element): readonly Element[];
580
634
 
635
+ /**
636
+ * Collects an element's ancestors in the flat tree, nearest first, up to and including a region.
637
+ *
638
+ * @param element - The element to climb from.
639
+ * @param region - The ancestor the climb stops at.
640
+ * @returns Every ancestor from the element's flat parent to the region, and every ancestor to the
641
+ * root element where the region is none of them.
642
+ *
643
+ * @remarks
644
+ * A step goes to the slot an element is assigned to, else to its parent element, else to the host
645
+ * of the shadow root it stands in, as {@link collectClippingAncestors} climbs.
646
+ *
647
+ * @example
648
+ * ```ts
649
+ * collectFlatAncestors(row, region).at(-1) === region // true for a row inside the region
650
+ * ```
651
+ */
652
+ export declare function collectFlatAncestors(element: Element, region: Element): readonly Element[];
653
+
654
+ /**
655
+ * Collects the elements under an element in the flat tree, in the order a browser paints them.
656
+ *
657
+ * @param element - The element whose content to walk.
658
+ * @returns Every element under it, each followed by its own content.
659
+ *
660
+ * @remarks
661
+ * The walk goes into a host's open shadow root in place of its light children, and from a slot to
662
+ * the elements assigned to it, or to its own children where none is assigned. A closed shadow root
663
+ * is unreachable, so a host carrying one is walked through its light children.
664
+ *
665
+ * @example
666
+ * ```ts
667
+ * collectFlatDescendants(host).length
668
+ * ```
669
+ */
670
+ export declare function collectFlatDescendants(element: Element): readonly Element[];
671
+
672
+ /**
673
+ * Collects the elements under a scroll region whose boxes lay out in its scrollable area, walking
674
+ * the flat tree.
675
+ *
676
+ * @param region - The scroll region whose content to walk.
677
+ * @returns Every element {@link collectFlatDescendants} reaches under the region, in flat-tree
678
+ * order, less each fixed or absolute box whose containing block lies outside the region and
679
+ * everything inside that box.
680
+ *
681
+ * @remarks
682
+ * A box whose containing block lies outside the region adds nothing to the region's scroll height.
683
+ * For each fixed-position element, the climb from it to the region, which
684
+ * {@link collectFlatAncestors} takes, looks for an ancestor {@link containsFixed} reports true for;
685
+ * for each absolutely positioned element, it looks for such an ancestor or a positioned one. An
686
+ * element whose climb finds none is left out with its content. A `:modal` dialog and a
687
+ * `:popover-open` element are laid out in the top layer, which a transformed ancestor does not
688
+ * contain, so one under such an ancestor is counted as a row.
689
+ *
690
+ * @example
691
+ * ```ts
692
+ * const rows = collectRegionRows(region)
693
+ * ```
694
+ */
695
+ export declare function collectRegionRows(region: Element): readonly Element[];
696
+
697
+ /**
698
+ * Collects the scroll containers in an element's subtree, the element included unless it is the
699
+ * body or the root element.
700
+ *
701
+ * @param element - The element whose subtree to walk. Default: the document's body.
702
+ * @returns Every element whose computed `overflow-x` or `overflow-y` value is the `auto` keyword,
703
+ * the `scroll` keyword, or the `hidden` keyword, in document order, and an empty list where the
704
+ * subtree holds none.
705
+ *
706
+ * @remarks
707
+ * Each of those keywords makes an element a scroll container, so script and `scrollIntoView` can
708
+ * move its scroll position whether or not it shows a scrollbar; the `clip` keyword and the `visible`
709
+ * keyword do not. The walk descends into each open shadow root after the host's own children. A
710
+ * closed shadow root is unreachable, so its containers stay out of the list. The body and the root
711
+ * element are left out, because their scroll is the window's.
712
+ *
713
+ * @example
714
+ * ```ts
715
+ * const placements = collectScrollContainers().map((container) => container.scrollTop)
716
+ * ```
717
+ */
718
+ export declare function collectScrollContainers(element?: Element): readonly Element[];
719
+
581
720
  /**
582
721
  * Collects the rendered boxes a person can scroll.
583
722
  *
@@ -642,6 +781,40 @@ export declare function collectShadowHosts(element: Element, root?: Node): reado
642
781
  */
643
782
  export declare function collectTabStops(root: Element, start: HTMLElement): Promise<readonly HTMLElement[]>;
644
783
 
784
+ /**
785
+ * Collects the vertical scroll regions an unrolled frame releases in an element's subtree, the
786
+ * element included unless it is the body or the root element.
787
+ *
788
+ * @param element - The element whose subtree to walk and whose box is the frame. Default: the
789
+ * document's body, whose frame is the page: the window's width, from the document's top down.
790
+ * @returns Every scroll container the {@link collectScrollContainers} helper finds whose computed
791
+ * `overflow-y` value is the `auto` keyword or the `scroll` keyword, whose `scrollHeight` exceeds its
792
+ * `clientHeight`, that the page shows, that is no form control, and whose box overlaps the frame,
793
+ * in document order.
794
+ *
795
+ * @remarks
796
+ * A region's hidden rows are its `scrollHeight` minus its `clientHeight`. A `hidden` overflow and a
797
+ * `clip` overflow are left out, because a page that hides rows there hides them by design. An
798
+ * `overflow-x: auto` wrapper computes an `overflow-y` value of `auto` too, so it is left out only
799
+ * where its rows fit. A text area, a list box, and an input, which {@link CAPTURE_CONTROLS} names,
800
+ * are left out, because their rows are the control's value. A region `checkVisibility` reports
801
+ * unshown, its `visibility` read included, is left out; the journey reader `isRendered` is not the
802
+ * test, because a region marked `aria-hidden` still paints. A region whose box lies wholly outside
803
+ * the frame, such as a navigation drawer a transform moves off the page, is left out. The walk
804
+ * reaches open shadow roots; a region inside a closed shadow root is unreachable and is left out.
805
+ * The `collectScrollRegions` journey reader answers a different question, which boxes a person can
806
+ * scroll on either axis, and reads no shadow root.
807
+ *
808
+ * @example
809
+ * ```ts
810
+ * const hidden = collectUnrolledRegions().reduce(
811
+ * (sum, region) => sum + region.scrollHeight - region.clientHeight,
812
+ * 0,
813
+ * )
814
+ * ```
815
+ */
816
+ export declare function collectUnrolledRegions(element?: Element): readonly Element[];
817
+
645
818
  /**
646
819
  * Sets one field's value and commits it, the way typing and then leaving the field does.
647
820
  *
@@ -718,6 +891,31 @@ export declare function computeNamePattern(name: string): RegExp;
718
891
  */
719
892
  export declare function computeOffset(box: DOMRectReadOnly, width: number, height: number): FrameOffset;
720
893
 
894
+ /**
895
+ * Reports whether an element is the containing block of the fixed-position boxes inside it.
896
+ *
897
+ * @param element - The element to read.
898
+ * @returns True if the element's computed `transform`, `translate`, `rotate`, `scale`,
899
+ * `perspective`, `filter`, or `backdrop-filter` value is other than the `none` keyword, its
900
+ * computed `contain` value carries layout or paint containment, its computed `container-type`
901
+ * value is the `size` keyword or the `inline-size` keyword, its computed `content-visibility`
902
+ * value is the `auto` keyword, its computed `transform-style` value is the `preserve-3d` keyword,
903
+ * or its computed `will-change` value names one of those transforming or filtering properties;
904
+ * false otherwise.
905
+ *
906
+ * @remarks
907
+ * A fixed-position box is laid out against the viewport unless an ancestor takes that role, and
908
+ * each of the listed properties makes the element take it. Every element this reports true for
909
+ * also contains absolutely positioned boxes. A containing block another property establishes is not
910
+ * read here.
911
+ *
912
+ * @example
913
+ * ```ts
914
+ * containsFixed(build('div', { attributes: { style: 'transform: translateZ(0)' } })) // true
915
+ * ```
916
+ */
917
+ export declare function containsFixed(element: Element): boolean;
918
+
721
919
  /**
722
920
  * Determines whether a node sits inside a root, through open shadow roots and frames.
723
921
  *
@@ -1169,7 +1367,7 @@ export declare function createPointerEvent(name: string, options?: PointerEventI
1169
1367
  *
1170
1368
  * An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
1171
1369
  * pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
1172
- * this run's own frame.
1370
+ * this run's own frame. The portfolio's `unrolled` option reaches every frame `place` writes.
1173
1371
  *
1174
1372
  * @example
1175
1373
  * ```ts
@@ -1580,6 +1778,11 @@ export declare interface FrameOptions {
1580
1778
  readonly height: number;
1581
1779
  /** Holds the element to shoot. Omit it to shoot the whole page. */
1582
1780
  readonly element?: Element | undefined;
1781
+ /**
1782
+ * If `true`, the frame also covers the rows every vertical scroll region hides; if `false` or
1783
+ * omitted, the frame ends where the document's own content ends.
1784
+ */
1785
+ readonly unrolled?: boolean | undefined;
1583
1786
  }
1584
1787
 
1585
1788
  /**
@@ -2078,6 +2281,32 @@ export declare function measureContrast(front: RGBA, back: RGBA): number;
2078
2281
  */
2079
2282
  export declare function measureLuminance(color: RGBA): number;
2080
2283
 
2284
+ /**
2285
+ * Measures the rows a scroll region's content lays out, whether or not its box shows them all.
2286
+ *
2287
+ * @param region - The scroll container to read.
2288
+ * @returns The height in CSS pixels from the top of the region's scrollable area to the bottom of
2289
+ * its content plus its bottom padding, rounded up to a whole row.
2290
+ *
2291
+ * @remarks
2292
+ * The `scrollHeight` property never reads less than the `clientHeight` property, so a region whose
2293
+ * rows fit reads its box rather than its rows, and the slack under its last row cannot be read
2294
+ * there. This reading can, because it is taken over the elements inside the region rather than
2295
+ * over its box: each element contributes its bottom edge plus its own bottom margin, capped at the
2296
+ * clip edge, as the {@link readClipEdge} helper measures it, of every clipping ancestor between it
2297
+ * and the region, and the largest contribution wins. The region's scroll offset is added back, so
2298
+ * a scrolled region reads the same rows as an unscrolled one. The elements are the ones
2299
+ * {@link collectRegionRows} reaches through the flat tree, so a host's shadow rows and a slot's
2300
+ * assigned rows count, and a fixed or absolute box laid out against a block outside the region
2301
+ * does not, because it adds nothing to the region's scroll height.
2302
+ *
2303
+ * @example
2304
+ * ```ts
2305
+ * const slack = region.clientHeight - measureRegion(region)
2306
+ * ```
2307
+ */
2308
+ export declare function measureRegion(region: Element): number;
2309
+
2081
2310
  /**
2082
2311
  * Names the tester root's attribute holding the media readings observed before the first stage.
2083
2312
  *
@@ -2308,6 +2537,11 @@ export declare interface PortfolioOptions {
2308
2537
  * nothing, writes nothing, and records nothing.
2309
2538
  */
2310
2539
  readonly enabled?: boolean;
2540
+ /**
2541
+ * If `true`, every frame `place` writes also covers the rows every vertical scroll region hides;
2542
+ * if `false` or omitted, each frame ends where the document's own content ends.
2543
+ */
2544
+ readonly unrolled?: boolean;
2311
2545
  }
2312
2546
 
2313
2547
  /**
@@ -2494,6 +2728,9 @@ export declare function readCaptureReader(): CaptureReader | undefined;
2494
2728
  * it, so `.café` defines `café` where 0.0.26 ended the class at the first code point outside ASCII
2495
2729
  * letters, digits, `_`, and `-` and defined `caf`. One rule's own tokens enter in code-unit order.
2496
2730
  *
2731
+ * A class named only in an `@scope` prelude counts as defined, so `@scope (.panel) to (.footer)`
2732
+ * defines `panel` and `footer`, and one prelude's tokens enter together in code-unit order.
2733
+ *
2497
2734
  * `@keyframes` children are outside that walk, so an animation's own rules define no token here.
2498
2735
  * Reach the animation itself through {@link findKeyframes}.
2499
2736
  *
@@ -3568,6 +3805,45 @@ export declare function render(markup: string): HTMLDivElement;
3568
3805
  */
3569
3806
  export declare function render<K extends keyof HTMLElementTagNameMap>(tag: K, classes: string): HTMLElementTagNameMap[K];
3570
3807
 
3808
+ /**
3809
+ * Renders the locator a capture refusal names an element by.
3810
+ *
3811
+ * @param element - The element to name.
3812
+ * @returns The path {@link renderSelector} renders, cut to its last {@link CAPTURE_LABEL_LIMIT}
3813
+ * characters behind a leading ellipsis where it is longer, and JSON-encoded.
3814
+ *
3815
+ * @remarks
3816
+ * The path carries ids the page wrote. Keeping its end keeps the steps nearest the element, and the
3817
+ * encoding keeps a page-authored id from faking or growing the message it stands in.
3818
+ *
3819
+ * @example
3820
+ * ```ts
3821
+ * renderLabel(requireValue(document.querySelector('#log'))) // '"div#log"'
3822
+ * ```
3823
+ */
3824
+ export declare function renderLabel(element: Element): string;
3825
+
3826
+ /**
3827
+ * Renders a selector path that locates an element from its nearest ancestor carrying an id.
3828
+ *
3829
+ * @param element - The element to locate.
3830
+ * @returns A path of `>`-joined steps, each the tag name with an escaped `#id` where the element
3831
+ * carries one and an `:nth-of-type()` position where a sibling shares its tag.
3832
+ *
3833
+ * @remarks
3834
+ * The path starts at the nearest ancestor carrying an id, else at the body or the root element, so
3835
+ * it stays short where the page names its landmarks. A step out of a shadow tree to its host is
3836
+ * written ` >>> `, which no selector engine reads: the path locates the element for a person or an
3837
+ * agent reading a refusal, and a closed shadow root is crossed the same way. The id is escaped with
3838
+ * `CSS.escape`, so a step names the attribute value the page wrote.
3839
+ *
3840
+ * @example
3841
+ * ```ts
3842
+ * renderSelector(requireValue(document.querySelector('#stage main'))) // 'div#stage > main'
3843
+ * ```
3844
+ */
3845
+ export declare function renderSelector(element: Element): string;
3846
+
3571
3847
  /**
3572
3848
  * Resolves one visible, focus-reachable interactive element by its exact accessible name. A
3573
3849
  * wholly-off-viewport target is scrolled into view before reachability is measured.
@@ -3781,13 +4057,25 @@ export declare function settleCapture(options?: SettleOptions): Promise<() => vo
3781
4057
  /**
3782
4058
  * Restages a capture until its content extent equals the pane height.
3783
4059
  *
3784
- * @remarks The stage limit bounds the recursion; a prepared pane is staged before accepting it.
4060
+ * @returns The regions an unrolled frame left out of its extent because each kept its height across
4061
+ * a staging, and an empty list for a plain frame.
4062
+ *
4063
+ * @remarks The stage limit bounds the recursion; a prepared pane is staged before accepting it. An
4064
+ * unrolled frame adds the rows its regions hide to the extent. `regions` maps each region tracked
4065
+ * so far to its height at the previous reading; omit it at the first call. A region whose height
4066
+ * did not change across a staging keeps a fixed height, so its hidden rows are left out of the
4067
+ * extent and out of the slack. After no other tracked region hides rows, the smallest slack among
4068
+ * the tracked regions that grew comes off the extent. A region a re-render disconnected is
4069
+ * dropped. The prepared restaging at the declared height reads afresh, because the pane did not
4070
+ * change. A staging the carried growth would land back on the current pane stages at the extent
4071
+ * instead, because a repeated pane reads every height unchanged. Thrown when the stage limit is
4072
+ * reached, naming on an unrolled frame every region still hiding rows.
3785
4073
  * @example
3786
4074
  * ```ts
3787
4075
  * await settleFrame({ path: 'frame.png', width: 390, height: 844 }, undefined, false)
3788
4076
  * ```
3789
4077
  */
3790
- export declare function settleFrame(options: FrameOptions, element: Element | undefined, prepared: boolean, pane?: number, covered?: number, stage?: number): Promise<void>;
4078
+ export declare function settleFrame(options: FrameOptions, element: Element | undefined, prepared: boolean, pane?: number, covered?: number, stage?: number, regions?: ReadonlyMap<Element, number>): Promise<readonly Element[]>;
3791
4079
 
3792
4080
  /**
3793
4081
  * Configures one capture settle: the time bounds of {@link WaitOptions} and whether the pointer