browser-debugger-cli 0.7.2 → 0.9.0

package/dist/runtime/dom/elementGeometry.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Where elements are relative to the viewport of the top-level page.
+ *
+ * The page-side scripts measure an element in top-level viewport coordinates
+ * (adding the offsets of the same-origin iframes it is in) together with what
+ * clips it: the viewports of those iframes and ancestors that cut off
+ * overflowing content (scroll containers, `overflow: hidden`). Classifying the
+ * measurements is done here, outside the page, so `dom query` and `dom layout`
+ * agree and the rules can be tested without a browser.
+ */
+import type { LayoutBox, LayoutPoint, LayoutSize } from '../../ipc/protocol/domTypes.js';
+import type { ViewportPosition } from '../../types.js';
+/** Measurements of one element ({@link ELEMENT_GEOMETRY_JS}). */
+export interface ElementGeometry {
+    /** Border box in top-level viewport coordinates */
+    rect: LayoutBox;
+    /** Area its iframes and overflow-clipping ancestors leave visible, in the same coordinates */
+    clip: LayoutBox | null;
+    /** Whether overlay scrollbars of the clipping containers show along the clip's right and bottom edges */
+    clipOverlay: OverlayEdges;
+    /** Innermost ancestor or iframe cutting off part of it, e.g. `ul#list` */
+    clipper: string | null;
+    /** Why it cannot be seen regardless of position, e.g. `display: none`, `clipped by div#acc: zero height` */
+    hidden: string | null;
+    /**
+     * Why it cannot be seen although it is rendered ({@link INVISIBLE_REASON_JS}),
+     * e.g. `opacity: 0 on div#menu`
+     */
+    invisible: string | null;
+    /** Inside an `inert` element: shown, but not interactive */
+    inert: boolean;
+    /** Fixed to the top-level viewport (it or a container is `position: fixed`): page scroll does not move it */
+    fixed: boolean;
+    /** It or an ancestor is `position: sticky`: page scroll moves it only until it sticks */
+    sticky?: boolean;
+    /** How far the top-level page can scroll from where it is now */
+    pageScroll: ScrollRange;
+    /**
+     * Why the top-level page cannot scroll although content is below the fold
+     * ({@link SCROLL_LOCK_JS}); null when it is not locked
+     */
+    scrollLock?: ScrollLock | null;
+    /** Offset of its document's viewport within the top-level viewport (iframes) */
+    offset: LayoutPoint;
+}
+/** What keeps the top-level page from scrolling ({@link SCROLL_LOCK_JS}). */
+export interface ScrollLock {
+    /** The styles locking it, e.g. `position: fixed, overflow: hidden on body` */
+    by: string;
+    /** A visible dialog that is likely the reason, e.g. `div#consent`; null when there is none */
+    dialog: string | null;
+}
+/** Edges of a viewport or clip along which overlay scrollbars (that take no space) show after a scroll. */
+export interface OverlayEdges {
+    right: boolean;
+    bottom: boolean;
+}
+/** Distances (CSS px, never negative) a page can scroll in each direction. */
+export interface ScrollRange {
+    left: number;
+    up: number;
+    right: number;
+    down: number;
+}
+/** How an element relates to the viewport ({@link classifyViewportPosition}). */
+export interface ViewportPlacement {
+    inViewport: ViewportPosition;
+    /** Share in view (1-99), for `partly` */
+    percentVisible?: number;
+    /** Why it is `hidden` */
+    hiddenReason?: string;
+    /**
+     * Page scroll that brings it fully into view, when the page can scroll there:
+     * the smallest one for an element partly in view, centring it for one out of view
+     */
+    scrollBy?: LayoutPoint;
+    /** Ancestor or iframe cutting it off (page scroll alone does not show it) */
+    clippedBy?: string;
+    /** Why page scroll cannot bring it fully into view ({@link OFF_SCREEN_REASONS}) */
+    offScreenReason?: string;
+}
+/** Why page scroll cannot bring an element that is not fully in view into view. */
+export declare const OFF_SCREEN_REASONS: {
+    readonly fixed: "fixed position, page scroll does not move it";
+    readonly sticky: "sticky position, page scroll moves it only until it sticks";
+    readonly outOfRange: "beyond the page's scroll range";
+};
+/**
+ * Page-side size of a window's viewport without scrollbars (the window size
+ * for quirks-mode documents, whose root element is as large as the content).
+ */
+export declare const VIEWPORT_SIZE_JS = "(view) => {\n  const root = view.document.documentElement;\n  const standards = view.document.compatMode === 'CSS1Compat' && root;\n  return {\n    width: standards ? root.clientWidth : view.innerWidth,\n    height: standards ? root.clientHeight : view.innerHeight\n  };\n}";
+/**
+ * Page-side distances a window's page can scroll in each direction from its
+ * current position. Right-to-left pages scroll to negative `scrollX`. Content
+ * that a scrolling body cuts off is reported through the body as a clipper.
+ */
+export declare const SCROLL_RANGE_JS = "(view) => {\n  const doc = view.document;\n  const scroller = doc.scrollingElement || doc.documentElement;\n  const maxX = Math.max(0, scroller.scrollWidth - scroller.clientWidth);\n  const maxY = Math.max(0, scroller.scrollHeight - scroller.clientHeight);\n  const rtl = view.scrollX < 0 || view.getComputedStyle(doc.documentElement).direction === 'rtl';\n  const left = rtl ? maxX + view.scrollX : view.scrollX;\n  return { left: Math.max(0, left), up: Math.max(0, view.scrollY), right: Math.max(0, maxX - left), down: Math.max(0, maxY - view.scrollY) };\n}";
+/**
+ * Page-side offset of an iframe's content (inside its border and padding)
+ * within the viewport of the document holding the iframe.
+ */
+export declare const FRAME_OFFSET_JS = "(frame) => {\n  const rect = frame.getBoundingClientRect();\n  const style = frame.ownerDocument.defaultView.getComputedStyle(frame);\n  return {\n    x: rect.left + frame.clientLeft + parseFloat(style.paddingLeft),\n    y: rect.top + frame.clientTop + parseFloat(style.paddingTop)\n  };\n}";
+/**
+ * Page-side test of computed styles: true when they only scale or move the
+ * box (no `rotate`, and a 2D `transform` matrix without rotation or skew), so
+ * its bounding box is the box itself, scaled.
+ */
+export declare const SCALES_ONLY_JS = "(style) => {\n  if (style.rotate && style.rotate !== 'none') return false;\n  if (!style.transform || style.transform === 'none') return true;\n  const matrix = /^matrix\\(([^)]*)\\)$/.exec(style.transform);\n  if (!matrix) return false;\n  const values = matrix[1].split(',').map(parseFloat);\n  return Math.abs(values[1]) < 1e-6 && Math.abs(values[2]) < 1e-6;\n}";
+/** Page-side test of a `clip-path` that cuts everything away: `inset()` with percentages leaving no area. */
+export declare const CLIP_PATH_CUTS_ALL_JS = "(clipPath) => {\n  const inset = /^inset\\(([^)]*)\\)/.exec(clipPath || '');\n  const values = inset ? inset[1].split(' round ')[0].trim().split(/\\s+/) : [];\n  if (values.length === 0 || values.some((v) => !/%$/.test(v))) return false;\n  const [top, right = top, bottom = top, left = right] = values.map(parseFloat);\n  return top + bottom >= 100 || left + right >= 100;\n}";
+/**
+ * Page-side test of a `clip` that cuts everything away: `rect()` with no area
+ * on an absolutely positioned or fixed element (the "visually hidden"
+ * pattern; `clip` applies to no other element).
+ */
+export declare const CLIP_RECT_CUTS_ALL_JS = "(position, clip) => {\n  if ((position !== 'absolute' && position !== 'fixed') || !/^rect\\(/.test(clip || '')) return false;\n  const edges = (clip.match(/-?[\\d.]+/g) || []).map(Number);\n  return edges.length === 4 && (edges[1] <= edges[3] || edges[2] <= edges[0]);\n}";
+/**
+ * Page-side measurement of an element ({@link ElementGeometry}): its box in
+ * top-level viewport coordinates, its clip by ancestors
+ * ({@link ANCESTOR_CLIP_JS}) and by the viewports of its iframes, why it
+ * cannot be seen at all (not rendered, or inside a clipping container
+ * collapsed to zero size), why a rendered one is still invisible
+ * ({@link INVISIBLE_REASON_JS}), whether it is inert (an `inert` element
+ * around it, through shadow roots) or fixed to the top-level viewport, and how
+ * far the top-level page can scroll ({@link SCROLL_RANGE_JS}) or what locks
+ * its scrolling ({@link SCROLL_LOCK_JS}). Content of a body fixed to lock the
+ * page is not counted as fixed: it is in-flow content the lock holds in place.
+ *
+ * Rendering is decided by `checkVisibility()`, so content Chrome skips
+ * (inside a closed `<details>`, under `content-visibility: hidden`) is hidden
+ * although it still has a box. Content skipped by `content-visibility: auto`
+ * is not: it is rendered once scrolled near the viewport.
+ */
+export declare const ELEMENT_GEOMETRY_JS: string;
+/**
+ * How a scroll brings an element into view: `centre` it (an element out of
+ * view, like `bdg dom scroll <selector>`, so sticky headers and fixed footers
+ * at the edges do not cover it), or the `minimal` scroll that shows all of
+ * it (an element partly in view: the part cut off at one edge).
+ */
+export type ScrollAim = 'centre' | 'minimal';
+/**
+ * Where along one axis a scroll should bring a span's start (in the current
+ * viewport coordinates): centred, or just inside the edge cutting it off; a
+ * span larger than the viewport gets its start aligned either way.
+ *
+ * @param start - Start of the span in viewport coordinates
+ * @param size - Length of the span
+ * @param viewSize - Length of the viewport
+ * @param aim - Centre it, or the smallest scroll showing all of it
+ * @returns Scroll that would do it (negative: back), before limiting it to the page
+ */
+export declare function scrollTarget(start: number, size: number, viewSize: number, aim: ScrollAim): number;
+/**
+ * Classify where an element is relative to the top-level viewport.
+ *
+ * Visible parts are what lies inside the viewport and the element's clip
+ * (iframes, overflow containers). An element with no visible part is `above`,
+ * `below`, `left` or `right` of the viewport (or of its clip, e.g. scrolled
+ * out of a list), and `hidden` when it is not rendered at all. Being inert
+ * does not change the position: inert elements are shown.
+ *
+ * @param geometry - Page-side measurements
+ * @param viewport - Top-level viewport size
+ * @returns Position, with the visible share, hidden reason, clipping
+ *   ancestor or page scroll when relevant
+ */
+export declare function classifyViewportPosition(geometry: ElementGeometry, viewport: LayoutSize): ViewportPlacement;
+//# sourceMappingURL=elementGeometry.d.ts.map