@viewlint/rules 0.0.1

package/dist/rules/overlapped-elements.js

@@ -0,0 +1,252 @@
+import { defineRule } from "viewlint/plugin";
+import { getDomHelpersHandle } from "../utils/getDomHelpersHandle.js";
+/**
+ * Detects elements that overlap unintentionally within the same layout context.
+ * - Elements must be visible in the viewport.
+ * - Elements positioned absolute/fixed are not candidates.
+ * - Overlap is only checked when both elements share the same nearest
+ *   absolute/fixed ancestor (or neither has one).
+ */
+export default defineRule({
+    meta: {
+        severity: "error",
+        docs: {
+            description: "Detects elements that overlap unintentionally",
+            recommended: true,
+        },
+    },
+    async run(context) {
+        const domHelpers = await getDomHelpersHandle(context.page);
+        await context.evaluate(({ report, scope, args: { domHelpers } }) => {
+            const OVERLAP_THRESHOLD = 5;
+            const MIN_ELEMENT_SIZE = 10;
+            const MIN_OVERLAP_PERCENT = 5;
+            const MIN_THIN_OVERLAP_PX = 12;
+            const MAX_THIN_OVERLAP_PERCENT = 20;
+            const MIN_NEGATIVE_MARGIN_OVERLAP_PERCENT = 50;
+            const getClippingAncestors = (el) => {
+                const ancestors = [];
+                let current = el.parentElement;
+                while (current) {
+                    const style = window.getComputedStyle(current);
+                    const clipsX = domHelpers.isClippingOverflowValue(style.overflowX);
+                    const clipsY = domHelpers.isClippingOverflowValue(style.overflowY);
+                    if (clipsX || clipsY) {
+                        ancestors.push({
+                            rect: current.getBoundingClientRect(),
+                            clipsX,
+                            clipsY,
+                        });
+                    }
+                    current = current.parentElement;
+                }
+                return ancestors;
+            };
+            const clipRectByAncestors = (rect, ancestors) => {
+                let left = rect.left, right = rect.right, top = rect.top, bottom = rect.bottom;
+                for (const ancestor of ancestors) {
+                    if (ancestor.clipsX) {
+                        left = Math.max(left, ancestor.rect.left);
+                        right = Math.min(right, ancestor.rect.right);
+                    }
+                    if (ancestor.clipsY) {
+                        top = Math.max(top, ancestor.rect.top);
+                        bottom = Math.min(bottom, ancestor.rect.bottom);
+                    }
+                }
+                const width = right - left, height = bottom - top;
+                if (width <= 0 || height <= 0)
+                    return null;
+                return new DOMRect(left, top, width, height);
+            };
+            const getRects = (el) => {
+                const clippingAncestors = getClippingAncestors(el);
+                const results = [];
+                for (const rect of el.getClientRects()) {
+                    const clipped = clipRectByAncestors(rect, clippingAncestors);
+                    if (!clipped)
+                        continue;
+                    if (clipped.width < MIN_ELEMENT_SIZE ||
+                        clipped.height < MIN_ELEMENT_SIZE)
+                        continue;
+                    results.push(clipped);
+                }
+                return results;
+            };
+            const getArea = (rects) => {
+                let total = 0;
+                for (const rect of rects)
+                    total += rect.width * rect.height;
+                return total;
+            };
+            const isCandidate = (el) => {
+                if (!domHelpers.isVisibleInViewport(el))
+                    return false;
+                const style = window.getComputedStyle(el);
+                return (style.position !== "absolute" &&
+                    style.position !== "fixed" &&
+                    style.position !== "sticky");
+            };
+            const hasTextDescendant = (el) => {
+                const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+                let node = walker.nextNode();
+                while (node) {
+                    if (node.textContent && node.textContent.trim().length > 0)
+                        return true;
+                    node = walker.nextNode();
+                }
+                return false;
+            };
+            const isFloatWrapPair = (a, b) => {
+                const styleA = window.getComputedStyle(a);
+                const styleB = window.getComputedStyle(b);
+                const floatA = styleA.float !== "none";
+                const floatB = styleB.float !== "none";
+                if (floatA === floatB)
+                    return false;
+                if (a.parentElement !== b.parentElement)
+                    return false;
+                const otherEl = floatA ? b : a;
+                const otherStyle = floatA ? styleB : styleA;
+                if (otherStyle.position === "absolute" ||
+                    otherStyle.position === "fixed")
+                    return false;
+                if (otherStyle.float !== "none")
+                    return false;
+                if (!hasTextDescendant(otherEl))
+                    return false;
+                return true;
+            };
+            const findLayoutRoot = (el) => {
+                let current = el.parentElement;
+                while (current) {
+                    const style = window.getComputedStyle(current);
+                    if (style.position === "absolute" || style.position === "fixed")
+                        return current;
+                    current = current.parentElement;
+                }
+                return null;
+            };
+            const rectsOverlap = (a, b) => {
+                if (a.right <= b.left + OVERLAP_THRESHOLD)
+                    return false;
+                if (a.left >= b.right - OVERLAP_THRESHOLD)
+                    return false;
+                if (a.bottom <= b.top + OVERLAP_THRESHOLD)
+                    return false;
+                if (a.top >= b.bottom - OVERLAP_THRESHOLD)
+                    return false;
+                return true;
+            };
+            const candidates = [];
+            const candidateByElement = new Map();
+            for (const el of scope.queryAll("*")) {
+                if (!domHelpers.isHtmlElement(el))
+                    continue;
+                if (!isCandidate(el))
+                    continue;
+                const rects = getRects(el);
+                if (rects.length === 0)
+                    continue;
+                const area = getArea(rects);
+                if (area === 0)
+                    continue;
+                const candidate = {
+                    el,
+                    rects,
+                    area,
+                    layoutRoot: findLayoutRoot(el),
+                };
+                candidates.push(candidate);
+                candidateByElement.set(el, candidate);
+            }
+            const computeOverlapMetrics = (first, second) => {
+                let maxOverlapArea = 0, maxOverlapWidth = 0, maxOverlapHeight = 0;
+                for (const rectA of first.rects) {
+                    for (const rectB of second.rects) {
+                        if (!rectsOverlap(rectA, rectB))
+                            continue;
+                        const intersection = domHelpers.getIntersectionRect(rectA, rectB);
+                        if (!intersection)
+                            continue;
+                        const area = intersection.width * intersection.height;
+                        if (area > maxOverlapArea) {
+                            maxOverlapArea = area;
+                            maxOverlapWidth = intersection.width;
+                            maxOverlapHeight = intersection.height;
+                        }
+                    }
+                }
+                if (maxOverlapArea === 0)
+                    return { percent: 0, area: 0, width: 0, height: 0 };
+                const smallerArea = Math.min(first.area, second.area);
+                if (smallerArea === 0) {
+                    return {
+                        percent: 0,
+                        area: maxOverlapArea,
+                        width: maxOverlapWidth,
+                        height: maxOverlapHeight,
+                    };
+                }
+                return {
+                    percent: Math.round((maxOverlapArea / smallerArea) * 100),
+                    area: maxOverlapArea,
+                    width: maxOverlapWidth,
+                    height: maxOverlapHeight,
+                };
+            };
+            const parentOverlaps = (child, other) => {
+                const parentElement = child.el.parentElement;
+                if (!parentElement)
+                    return false;
+                const parentCandidate = candidateByElement.get(parentElement);
+                if (!parentCandidate)
+                    return false;
+                if (parentCandidate.layoutRoot !== other.layoutRoot)
+                    return false;
+                if (parentCandidate.el.contains(other.el))
+                    return false;
+                return (computeOverlapMetrics(parentCandidate, other).percent >=
+                    MIN_OVERLAP_PERCENT);
+            };
+            for (let i = 0; i < candidates.length; i++) {
+                const a = candidates[i];
+                if (!a)
+                    continue;
+                for (let j = i + 1; j < candidates.length; j++) {
+                    const b = candidates[j];
+                    if (!b)
+                        continue;
+                    if (a.layoutRoot !== b.layoutRoot)
+                        continue;
+                    if (a.el.contains(b.el) || b.el.contains(a.el))
+                        continue;
+                    const overlap = computeOverlapMetrics(a, b);
+                    if (overlap.percent < MIN_OVERLAP_PERCENT)
+                        continue;
+                    if (parentOverlaps(a, b) || parentOverlaps(b, a))
+                        continue;
+                    if (isFloatWrapPair(a.el, b.el))
+                        continue;
+                    const isThinOverlap = (overlap.width < MIN_THIN_OVERLAP_PX ||
+                        overlap.height < MIN_THIN_OVERLAP_PX) &&
+                        overlap.percent < MAX_THIN_OVERLAP_PERCENT;
+                    if (isThinOverlap)
+                        continue;
+                    const hasNegMargin = domHelpers.hasNegativeMargin(a.el) ||
+                        domHelpers.hasNegativeMargin(b.el);
+                    if (hasNegMargin &&
+                        overlap.percent < MIN_NEGATIVE_MARGIN_OVERLAP_PERCENT)
+                        continue;
+                    report({
+                        message: `Elements overlap by ${overlap.percent}% of the smaller element's area`,
+                        element: a.el,
+                        relations: [
+                            { description: "Overlapping element", element: b.el },
+                        ],
+                    });
+                }
+            }
+        }, { domHelpers });
+    },
+});

package/dist/rules/space-misuse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Detects containers with irregular spacing around their content.
+ * Reports when empty space around content is severely asymmetric.
+ */
+declare const _default: import("viewlint").RuleDefinition<undefined>;
+export default _default;
+//# sourceMappingURL=space-misuse.d.ts.map

package/dist/rules/space-misuse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-misuse.d.ts","sourceRoot":"","sources":["../../src/rules/space-misuse.ts"],"names":[],"mappings":"AAGA;;;GAGG;;AACH,wBA+RE"}

package/dist/rules/space-misuse.js

@@ -0,0 +1,204 @@
+import { defineRule } from "viewlint/plugin";
+import { getDomHelpersHandle } from "../utils/getDomHelpersHandle.js";
+/**
+ * Detects containers with irregular spacing around their content.
+ * Reports when empty space around content is severely asymmetric.
+ */
+export default defineRule({
+    meta: {
+        severity: "warn",
+        docs: {
+            description: "Detects containers with irregularly distributed empty space around content",
+            recommended: false,
+        },
+    },
+    async run(context) {
+        const domHelpers = await getDomHelpersHandle(context.page);
+        await context.evaluate(({ report, scope, args: { domHelpers } }) => {
+            void report;
+            // Thresholds
+            const MIN_CONTAINER_SIZE = 50, MIN_CONTENT_SIZE = 10;
+            const IRREGULARITY_RATIO = 6, MIN_GAP_DIFF = 40, MIN_LARGE_GAP = 60;
+            const SIBLING_GAP_THRESHOLD = 20, SIBLING_TOLERANCE = 10;
+            const LOW_FILL = 0.25, MIN_WASTED = 100, BALANCED_RATIO = 3;
+            const MAX_SIMPLE_CHILDREN = 3, MAX_SIMPLE_AREA = 0.3;
+            const DOMINANT_CHILD = 0.5, MIN_FILL = 0.2;
+            const getChildrenBounds = (container) => {
+                let minL = Infinity, minT = Infinity, maxR = -Infinity, maxB = -Infinity;
+                let hasContent = false;
+                for (const child of container.children) {
+                    if (!domHelpers.isRenderableElement(child) ||
+                        !domHelpers.isVisible(child))
+                        continue;
+                    const r = child.getBoundingClientRect();
+                    if (!domHelpers.hasRectSize(r))
+                        continue;
+                    hasContent = true;
+                    minL = Math.min(minL, r.left);
+                    minT = Math.min(minT, r.top);
+                    maxR = Math.max(maxR, r.right);
+                    maxB = Math.max(maxB, r.bottom);
+                }
+                return hasContent
+                    ? new DOMRect(minL, minT, maxR - minL, maxB - minT)
+                    : null;
+            };
+            const isLeafContainer = (el) => {
+                const style = window.getComputedStyle(el);
+                if (style.display === "grid")
+                    return false;
+                const rect = el.getBoundingClientRect();
+                if (!domHelpers.hasRectSize(rect))
+                    return false;
+                let count = 0, maxRatio = 0, totalArea = 0;
+                const containerArea = rect.width * rect.height;
+                for (const child of el.children) {
+                    if (!domHelpers.isRenderableElement(child) ||
+                        !domHelpers.isVisible(child))
+                        continue;
+                    const r = child.getBoundingClientRect();
+                    if (!domHelpers.hasRectSize(r))
+                        continue;
+                    count++;
+                    const area = r.width * r.height;
+                    totalArea += area;
+                    if (containerArea > 0)
+                        maxRatio = Math.max(maxRatio, area / containerArea);
+                }
+                if (count === 0)
+                    return false;
+                const totalRatio = containerArea > 0 ? totalArea / containerArea : 0;
+                return count <= MAX_SIMPLE_CHILDREN
+                    ? totalRatio < MAX_SIMPLE_AREA
+                    : maxRatio >= DOMINANT_CHILD;
+            };
+            const getSiblingFilled = (container, cRect, gaps) => {
+                const filled = {
+                    top: false,
+                    right: false,
+                    bottom: false,
+                    left: false,
+                };
+                const parent = container.parentElement;
+                if (!parent)
+                    return filled;
+                for (const sib of parent.children) {
+                    if (!domHelpers.isRenderableElement(sib) ||
+                        !(sib instanceof HTMLElement))
+                        continue;
+                    if (sib === container || !domHelpers.isVisible(sib))
+                        continue;
+                    const s = sib.getBoundingClientRect();
+                    if (!domHelpers.hasRectSize(s))
+                        continue;
+                    const hOverlap = s.left < cRect.right && s.right > cRect.left;
+                    const vOverlap = s.top < cRect.bottom && s.bottom > cRect.top;
+                    if (gaps.top > SIBLING_GAP_THRESHOLD &&
+                        hOverlap &&
+                        s.bottom <= cRect.top + SIBLING_TOLERANCE &&
+                        s.bottom >= cRect.top - gaps.top) {
+                        filled.top = true;
+                    }
+                    if (gaps.bottom > SIBLING_GAP_THRESHOLD &&
+                        hOverlap &&
+                        s.top >= cRect.bottom - SIBLING_TOLERANCE &&
+                        s.top <= cRect.bottom + gaps.bottom) {
+                        filled.bottom = true;
+                    }
+                    if (gaps.left > SIBLING_GAP_THRESHOLD &&
+                        vOverlap &&
+                        s.right <= cRect.left + SIBLING_TOLERANCE &&
+                        s.right >= cRect.left - gaps.left) {
+                        filled.left = true;
+                    }
+                    if (gaps.right > SIBLING_GAP_THRESHOLD &&
+                        vOverlap &&
+                        s.left >= cRect.right - SIBLING_TOLERANCE &&
+                        s.left <= cRect.right + gaps.right) {
+                        filled.right = true;
+                    }
+                }
+                return filled;
+            };
+            const checkAxis = (gapA, gapB, sideA, sideB, filledA, filledB) => {
+                const min = Math.min(gapA, gapB), max = Math.max(gapA, gapB);
+                if (max < MIN_LARGE_GAP || max - min < MIN_GAP_DIFF)
+                    return null;
+                const largeSide = gapA > gapB ? sideA : sideB;
+                if (gapA > gapB ? filledA : filledB)
+                    return null;
+                if (min <= 2 && max >= MIN_LARGE_GAP) {
+                    const flush = gapA <= 2 ? sideA : sideB;
+                    const opp = gapA <= 2 ? sideB : sideA;
+                    return `content is flush with ${flush} edge, ${Math.round(max)}px gap on ${opp}`;
+                }
+                if (min > 0) {
+                    const ratio = max / min;
+                    if (ratio < IRREGULARITY_RATIO)
+                        return null;
+                    const smallSide = gapA > gapB ? sideB : sideA;
+                    return `${largeSide} gap (${Math.round(max)}px) is ${ratio.toFixed(1)}x larger than ${smallSide} (${Math.round(min)}px)`;
+                }
+                return null;
+            };
+            const checkPadding = (fill, gapA, gapB, dim) => {
+                if (fill >= LOW_FILL)
+                    return null;
+                const total = gapA + gapB;
+                if (total < MIN_WASTED)
+                    return null;
+                const min = Math.min(gapA, gapB), max = Math.max(gapA, gapB);
+                if (min > 0 && max / min > BALANCED_RATIO)
+                    return null;
+                return `content fills only ${Math.round(fill * 100)}% of ${dim} space (${Math.round(total)}px unused)`;
+            };
+            const analyze = (container, cRect, content) => {
+                const fillH = content.width / cRect.width;
+                const fillV = content.height / cRect.height;
+                if (fillH < MIN_FILL && fillV < MIN_FILL)
+                    return null;
+                const gaps = {
+                    top: content.top - cRect.top,
+                    right: cRect.right - content.right,
+                    bottom: cRect.bottom - content.bottom,
+                    left: content.left - cRect.left,
+                };
+                const filled = getSiblingFilled(container, cRect, gaps);
+                const issues = [];
+                const hIssue = checkAxis(gaps.left, gaps.right, "left", "right", filled.left, filled.right);
+                if (hIssue)
+                    issues.push(hIssue);
+                const vIssue = checkAxis(gaps.top, gaps.bottom, "top", "bottom", filled.top, filled.bottom);
+                if (vIssue)
+                    issues.push(vIssue);
+                const hPad = checkPadding(fillH, gaps.left, gaps.right, "horizontal");
+                if (hPad && !hIssue)
+                    issues.push(hPad);
+                const vPad = checkPadding(fillV, gaps.top, gaps.bottom, "vertical");
+                if (vPad && !vIssue)
+                    issues.push(vPad);
+                return issues.length > 0
+                    ? `Irregular spacing: ${issues.join("; ")}`
+                    : null;
+            };
+            for (const el of scope.queryAll("*")) {
+                if (!domHelpers.isHtmlElement(el) || !domHelpers.isVisible(el))
+                    continue;
+                if (el.children.length === 0)
+                    continue;
+                const cRect = el.getBoundingClientRect();
+                if (!domHelpers.hasRectSize(cRect, MIN_CONTAINER_SIZE, MIN_CONTAINER_SIZE))
+                    continue;
+                if (!isLeafContainer(el))
+                    continue;
+                const content = getChildrenBounds(el);
+                if (!content ||
+                    !domHelpers.hasRectSize(content, MIN_CONTENT_SIZE, MIN_CONTENT_SIZE))
+                    continue;
+                const msg = analyze(el, cRect, content);
+                if (msg)
+                    report({ message: msg, element: el });
+            }
+        }, { domHelpers });
+    },
+});

package/dist/rules/text-contrast.d.ts

@@ -0,0 +1,14 @@
+declare global {
+    interface Window {
+        __viewlint_finder?: (el: Element) => string;
+    }
+}
+/**
+ * Detects text with low contrast against its background.
+ *
+ * Uses screenshot-based analysis to sample the actual rendered background
+ * color behind text elements, then calculates WCAG contrast ratio.
+ */
+declare const _default: import("viewlint").RuleDefinition<undefined>;
+export default _default;
+//# sourceMappingURL=text-contrast.d.ts.map

package/dist/rules/text-contrast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-contrast.d.ts","sourceRoot":"","sources":["../../src/rules/text-contrast.ts"],"names":[],"mappings":"AAIA,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,MAAM;QACf,iBAAiB,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,MAAM,CAAA;KAC3C;CACD;AAED;;;;;GAKG;;AACH,wBAkRE"}