diff --git a/README.md b/README.md
index 63e2333..5c178eb 100644
--- a/README.md
+++ b/README.md
@@ -56,13 +56,30 @@ Check out the [tests](./src/__tests__/index.ts) for some examples.
## API
-### `visualHTML(div: Element, options?: { shallow?: boolean })`
+### `visualHTML(div: Element, options?: { shallow?: boolean, styleRules?: SelectorWithStyles[] })`
```javascript
visualHTML(document.body); // Returns the visual information of all nested elements in the body.
visualHTML(document.body, { shallow: true }); // Returns just visual information for the `` element.
```
+### `getDocumentStyleRules(document: Document)`
+
+Every capture reads and specificity sorts the document's style rules, which is
+the bulk of its work. A suite capturing many elements against the same
+stylesheets can do that once and hand the result to each call:
+
+```javascript
+const styleRules = getDocumentStyleRules(document);
+
+for (const el of elements) {
+ snapshot(visualHTML(el, { styleRules }));
+}
+```
+
+Media conditions are evaluated as the rules are read, so parse again whenever
+the viewport changes.
+
## How it works
`visual-html` works by building up an HTML representation of the DOM including only attributes that account for the visual display of the element.
diff --git a/src/__tests__/index.ts b/src/__tests__/index.ts
index 5abcf01..2aa33ac 100644
--- a/src/__tests__/index.ts
+++ b/src/__tests__/index.ts
@@ -1,4 +1,4 @@
-import visualHTML from "..";
+import visualHTML, { getDocumentStyleRules } from "..";
const { matchMedia: _matchMedia } = window;
const { supports: _supports } =
@@ -370,3 +370,129 @@ function testHTML(html: string, styles: string = "") {
document.head.removeChild(style);
return result;
}
+
+test("styles an element from pre-parsed rules after its stylesheet is gone", () => {
+ const style = document.createElement("style");
+ style.innerHTML = ".parsed { color: green; }";
+ document.head.appendChild(style);
+ const div = document.createElement("div");
+ div.className = "parsed";
+ document.body.appendChild(div);
+
+ const styleRules = getDocumentStyleRules(document);
+ document.head.removeChild(style);
+ const result = visualHTML(div, { styleRules });
+ document.body.removeChild(div);
+
+ expect(result).toMatchInlineSnapshot(`""`);
+});
+
+test("keeps urls as authored rather than resolved against the document", () => {
+ expect(
+ testHTML(`
+
+ `)
+ ).toMatchInlineSnapshot(`
+ ""
+ `);
+});
+
+test("keeps img dimensions as authored rather than as loaded", () => {
+ expect(
+ testHTML(`
+
+ `)
+ ).toMatchInlineSnapshot(`
+ ""
+ `);
+});
+
+test("omits img dimensions when the attributes are absent", () => {
+ expect(
+ testHTML(`
+
+ `)
+ ).toMatchInlineSnapshot(`""`);
+});
+
+test("includes the candidate list of a responsive image", () => {
+ expect(
+ testHTML(`
+
+ `)
+ ).toMatchInlineSnapshot(`
+ ""
+ `);
+});
+
+test("keeps the href that makes an anchor a link", () => {
+ // Without it the anchor loses the user agent's link colour, underline and
+ // pointer cursor.
+ expect(
+ testHTML(`
+ link
+ `)
+ ).toMatchInlineSnapshot(`
+ "
+ link
+ "
+ `);
+});
+
+test("quotes attributes so values containing quotes survive parsing", () => {
+ const output = testHTML(
+ `
text
`,
+ `.quoted {
+ background-image: url("cat.png?a=1&b=2");
+ font-family: "Market Sans", Arial;
+ position: absolute;
+ }`
+ );
+
+ const parsed = document.createElement("div");
+ parsed.innerHTML = output;
+ const style = (parsed.firstElementChild as HTMLElement).style;
+
+ expect(style.backgroundImage).toContain("cat.png?a=1&b=2");
+ expect(style.fontFamily).toContain("Market Sans");
+ // Everything after the quoted value used to be lost with the attribute.
+ expect(style.position).toBe("absolute");
+});
+
+test("does not reuse defaults across elements with different attributes", () => {
+ // A checkbox is border-box by default where a text input is content-box, so
+ // an input that declares border-box only shows up in one of the two.
+ expect(
+ testHTML(
+ `
+
+
+ `,
+ `.sized { box-sizing: border-box; }`
+ )
+ ).toMatchInlineSnapshot(`
+ "
+ "
+ `);
+});
+
+test("keeps an initial the author wrote", () => {
+ expect(
+ testHTML(
+ `
+
+ `,
+ `.reset { background-color: initial; }`
+ )
+ ).toMatchInlineSnapshot(`""`);
+});
diff --git a/src/attributes.ts b/src/attributes.ts
index 0e333cc..1b8fe5d 100644
--- a/src/attributes.ts
+++ b/src/attributes.ts
@@ -1,4 +1,4 @@
-import { HTML_PROPERTIES } from "./html-properties";
+import { DERIVED_PROPERTIES, HTML_PROPERTIES } from "./html-properties";
/**
* Given an element, returns any attributes that have a cause a visual change.
@@ -18,9 +18,11 @@ export function getVisualAttributes(el: Element) {
const { alias, tests } =
HTML_PROPERTIES[prop as keyof typeof HTML_PROPERTIES];
const name = alias || prop;
- const value = el[prop];
+ const isDerived = DERIVED_PROPERTIES.has(prop);
+ const value = isDerived ? el.getAttribute(name) : el[prop];
+ const defaultValue = isDerived ? null : defaults[prop];
- if (value !== defaults[prop]) {
+ if (value !== defaultValue) {
for (const test of tests) {
if (test(el as any)) {
(visualAttributes || (visualAttributes = [])).push({ name, value });
diff --git a/src/default-styles.ts b/src/default-styles.ts
index f8d21fd..55d49ec 100644
--- a/src/default-styles.ts
+++ b/src/default-styles.ts
@@ -6,17 +6,27 @@ let supportsPseudoElements: boolean | undefined;
* an element in an iframe without any styles and reading the default computed styles.
*/
export function getDefaultStyles(el: Element, pseudo: string | null) {
- const key = `${el.namespaceURI}:${el.localName}:${pseudo}`;
+ const unstyled = el.cloneNode(false) as Element;
+ unstyled.removeAttribute("style");
+ // User agent styles select on attributes too: a checkbox has none of the
+ // border, padding and background a text input has.
+ const doc = el.ownerDocument!;
+ const key = `${el.namespaceURI}:${unstyled.outerHTML}:${pseudo}:${doc.compatMode}`;
let cached = cache[key];
if (!cached) {
- const doc = el.ownerDocument!;
const frame = doc.createElement("iframe");
doc.body.appendChild(frame);
const frameDoc = frame.contentDocument!;
+ // A blank frame is in quirks mode, where an input is border-box rather
+ // than content-box; match the document being captured.
+ if (doc.compatMode === "CSS1Compat") {
+ frameDoc.open();
+ frameDoc.write("");
+ frameDoc.close();
+ }
const frameWindow = frameDoc.defaultView!;
- const clone = frameDoc.importNode(el, false);
- clone.removeAttribute("style");
+ const clone = frameDoc.importNode(unstyled, false);
frameDoc.body.appendChild(clone);
cached = cache[key] = cloneStyles(
@@ -29,6 +39,24 @@ export function getDefaultStyles(el: Element, pseudo: string | null) {
return cached;
}
+let initialStyles: { [x: string]: unknown } | undefined;
+
+/**
+ * Gets what a declared `initial` resolves to. These belong to CSS rather than
+ * to any element, so one probe answers for every capture.
+ */
+export function getInitialStyles(doc: Document) {
+ if (!initialStyles) {
+ const probe = doc.createElement("div");
+ probe.style.setProperty("all", "initial");
+ doc.body.appendChild(probe);
+ initialStyles = cloneStyles(doc.defaultView!.getComputedStyle(probe));
+ doc.body.removeChild(probe);
+ }
+
+ return initialStyles;
+}
+
function cloneStyles(styles: CSSStyleDeclaration) {
const result = Object.create(null) as { [x: string]: unknown };
diff --git a/src/html-properties.ts b/src/html-properties.ts
index b662189..4ba5901 100644
--- a/src/html-properties.ts
+++ b/src/html-properties.ts
@@ -75,10 +75,6 @@ export const HTML_PROPERTIES = {
alias: false,
tests: [test("area")],
},
- currentSrc: {
- alias: "src",
- tests: [test(["audio", "img", "source", "video"])],
- },
data: {
alias: false,
tests: [test("object")],
@@ -119,6 +115,10 @@ export const HTML_PROPERTIES = {
alias: false,
tests: [test("meter")],
},
+ href: {
+ alias: false,
+ tests: [test(["a", "area"])],
+ },
inputMode: {
alias: "inputmode",
tests: [
@@ -211,12 +211,18 @@ export const HTML_PROPERTIES = {
},
src: {
alias: false,
- tests: [test(["embed", "iframe", "track"])],
+ tests: [
+ test(["audio", "embed", "iframe", "img", "source", "track", "video"]),
+ ],
},
srcdoc: {
alias: false,
tests: [test("iframe")],
},
+ srcset: {
+ alias: false,
+ tests: [test(["img", "source"])],
+ },
sizes: {
alias: false,
tests: [test(["img", "source"])],
@@ -254,6 +260,21 @@ export const HTML_PROPERTIES = {
},
} as const;
+/**
+ * Properties reporting a value the author never wrote: urls resolved against
+ * the document, and the natural size of a media element once it has loaded.
+ * These are read from the content attribute instead.
+ */
+export const DERIVED_PROPERTIES = new Set([
+ "background",
+ "data",
+ "height",
+ "href",
+ "poster",
+ "src",
+ "width",
+]);
+
function isInputWithBoundaries(input: HTMLInputElement) {
return /^(?:number|range|date|datetime-local|year|month|week|day|time)$/.test(
input.type
diff --git a/src/index.ts b/src/index.ts
index d627813..d50fff4 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -8,6 +8,7 @@ import {
} from "./stylesheets";
export { VisualData, Options };
+export { getDocumentStyleRules };
const ELEMENT_TYPE = 1;
const TEXT_TYPE = 3;
@@ -20,7 +21,8 @@ export default function visualHTML(el: Element, options: Options = {}) {
return stringifyVisualData(
getVisualData(el, {
...options,
- styleRules: getDocumentStyleRules(el.ownerDocument!),
+ styleRules:
+ options.styleRules ?? getDocumentStyleRules(el.ownerDocument!),
})
);
}
diff --git a/src/properties.ts b/src/properties.ts
new file mode 100644
index 0000000..2c67439
--- /dev/null
+++ b/src/properties.ts
@@ -0,0 +1,219 @@
+const LOGICAL_PROPERTY = /(^|-)(inline|block)(-|$)/;
+const NONE: string[] = [];
+const logicalNamesByFlow = new Map>();
+let shorthandNames: ShorthandNames | undefined;
+
+interface ShorthandNames {
+ byLonghand: Map;
+ byShorthand: Map;
+}
+
+/**
+ * Properties an element takes from its parent when it declares nothing, so
+ * declaring one at its default value is not the no-op it is for the rest.
+ */
+export const INHERITED_PROPERTIES = new Set([
+ "azimuth",
+ "border-collapse",
+ "border-spacing",
+ "caption-side",
+ "caret-color",
+ "color",
+ "color-scheme",
+ "cursor",
+ "direction",
+ "empty-cells",
+ "font-family",
+ "font-feature-settings",
+ "font-kerning",
+ "font-optical-sizing",
+ "font-size",
+ "font-size-adjust",
+ "font-stretch",
+ "font-style",
+ "font-variant",
+ "font-variant-caps",
+ "font-variant-east-asian",
+ "font-variant-ligatures",
+ "font-variant-numeric",
+ "font-variation-settings",
+ "font-weight",
+ "hyphens",
+ "image-rendering",
+ "letter-spacing",
+ "line-height",
+ "list-style-image",
+ "list-style-position",
+ "list-style-type",
+ "orphans",
+ "overflow-wrap",
+ "paint-order",
+ "pointer-events",
+ "print-color-adjust",
+ "quotes",
+ "ruby-align",
+ "ruby-position",
+ "scrollbar-color",
+ "tab-size",
+ "text-align",
+ "text-align-last",
+ "text-anchor",
+ "text-indent",
+ "text-justify",
+ "text-rendering",
+ "text-shadow",
+ "text-size-adjust",
+ "text-transform",
+ "text-underline-offset",
+ "text-underline-position",
+ "text-wrap",
+ "visibility",
+ "white-space",
+ "white-space-collapse",
+ "widows",
+ "word-break",
+ "word-spacing",
+ "writing-mode",
+]);
+
+/**
+ * Given a longhand, returns the shorthands that write it, most specific first.
+ * A shorthand written with a var() cannot be split until substitution, so its
+ * longhands enumerate with no value and only the shorthand carries one.
+ */
+export function getShorthandsFor(doc: Document, longhand: string) {
+ return getShorthandNames(doc).byLonghand.get(longhand) || NONE;
+}
+
+/**
+ * Given a declared property, returns the properties it writes under the names
+ * the cascade settles them by: a shorthand writes each of its longhands, and a
+ * logical property writes the physical one it resolves to for the element.
+ */
+export function getWrittenProperties(el: Element, name: string) {
+ const doc = el.ownerDocument!;
+ const written = getShorthandNames(doc).byShorthand.get(name) || [name];
+
+ if (!written.some(isLogical)) {
+ return written;
+ }
+ const logicalNames = getLogicalNames(el);
+
+ return written.map((property) => logicalNames.get(property) || property);
+}
+
+function isLogical(name: string) {
+ return LOGICAL_PROPERTY.test(name);
+}
+
+function getLogicalNames(el: Element) {
+ const doc = el.ownerDocument!;
+ const { direction, writingMode } = doc.defaultView!.getComputedStyle(el);
+ const flow = `${direction}|${writingMode}`;
+ let names = logicalNamesByFlow.get(flow);
+
+ if (!names) {
+ logicalNamesByFlow.set(
+ flow,
+ (names = buildLogicalNames(doc, direction, writingMode))
+ );
+ }
+
+ return names;
+}
+
+/**
+ * Reads the names from a style declaration rather than a list of our own, so
+ * whatever the browser supports is covered: setting a property to a css wide
+ * keyword expands it into the longhands it writes.
+ */
+function getShorthandNames(doc: Document) {
+ return (shorthandNames = shorthandNames || buildShorthandNames(doc));
+}
+
+function buildShorthandNames(doc: Document): ShorthandNames {
+ const scratch = doc.createElement("div").style;
+ const expansions: Array<[string, string[]]> = [];
+
+ for (const idlName in scratch) {
+ const name = idlName
+ .replace(/^webkit/, "Webkit")
+ .replace(/[A-Z]/g, (letter) => "-" + letter.toLowerCase());
+ scratch.cssText = "";
+ try {
+ scratch.setProperty(name, "inherit");
+ } catch {
+ continue;
+ }
+ const longhands = Array.from(scratch);
+ if (
+ longhands.length > 1 ||
+ (longhands.length === 1 && longhands[0] !== name)
+ ) {
+ expansions.push([name, longhands]);
+ }
+ }
+
+ // Fewer longhands means a more specific shorthand: `border-top` is a better
+ // answer for `border-top-width` than `border` is, and `all` is the worst.
+ expansions.sort((a, b) => a[1].length - b[1].length);
+ const byLonghand = new Map();
+ for (const [shorthand, longhands] of expansions) {
+ for (const longhand of longhands) {
+ const found = byLonghand.get(longhand);
+ if (found) {
+ found.push(shorthand);
+ } else {
+ byLonghand.set(longhand, [shorthand]);
+ }
+ }
+ }
+
+ return { byLonghand, byShorthand: new Map(expansions) };
+}
+
+/**
+ * Declares each logical property on a throwaway element in the given writing
+ * mode to see which physical property takes the value.
+ */
+function buildLogicalNames(
+ doc: Document,
+ direction: string,
+ writingMode: string
+) {
+ const window = doc.defaultView!;
+ const probe = doc.createElement("div");
+ probe.style.setProperty("direction", direction);
+ probe.style.setProperty("writing-mode", writingMode);
+ doc.body.appendChild(probe);
+
+ const names = Array.from(window.getComputedStyle(probe));
+ const physicalNames = names.filter((name) => !isLogical(name));
+ const logicalNames = new Map();
+
+ for (const name of names.filter(isLogical)) {
+ const marker = markerFor(name);
+ probe.style.setProperty(name, marker);
+ const styles = window.getComputedStyle(probe);
+ const physical = physicalNames.find(
+ (candidate) => styles.getPropertyValue(candidate) === marker
+ );
+ if (physical) {
+ logicalNames.set(name, physical);
+ }
+ probe.style.removeProperty(name);
+ }
+
+ doc.body.removeChild(probe);
+
+ return logicalNames;
+}
+
+/** A value the property accepts and nothing else on a bare element holds. */
+function markerFor(name: string) {
+ if (name.endsWith("-color")) {
+ return "rgb(1, 2, 3)";
+ }
+
+ return name.endsWith("-style") ? "dotted" : "13px";
+}
diff --git a/src/stringify.ts b/src/stringify.ts
index 3b1227b..11e2d37 100644
--- a/src/stringify.ts
+++ b/src/stringify.ts
@@ -38,7 +38,13 @@ function printAttributes(data: VisualData) {
for (const { name, value } of attributes) {
parts.push(
name +
- (value === true || value === "" ? "" : `=${JSON.stringify(value)}`)
+ (value === true || value === ""
+ ? ""
+ : `=${
+ typeof value === "string"
+ ? quoteAttribute(value)
+ : JSON.stringify(value)
+ }`)
);
}
}
@@ -55,7 +61,19 @@ function printStyle({ styles }: VisualData) {
return "";
}
- return `style="${printProperties(styles)}"`;
+ return `style=${quoteAttribute(printProperties(styles))}`;
+}
+
+/**
+ * Quotes a value with a character it does not itself contain, so that markup
+ * holding a url("…") or a quoted font name can still be parsed back.
+ */
+function quoteAttribute(value: string) {
+ const escaped = value.replace(/&/g, "&");
+
+ return escaped.includes('"') && !escaped.includes("'")
+ ? `'${escaped}'`
+ : `"${escaped.replace(/"/g, """)}"`;
}
function printChildren(data: VisualData) {
diff --git a/src/stylesheets.ts b/src/stylesheets.ts
index a769b21..1b09204 100644
--- a/src/stylesheets.ts
+++ b/src/stylesheets.ts
@@ -1,7 +1,12 @@
import { compare, calculate } from "specificity";
import splitSelectors from "./split-selector";
import { SelectorWithStyles } from "./types";
-import { getDefaultStyles } from "./default-styles";
+import { getDefaultStyles, getInitialStyles } from "./default-styles";
+import {
+ getShorthandsFor,
+ getWrittenProperties,
+ INHERITED_PROPERTIES,
+} from "./properties";
const pseudoElementRegex =
/([(>~|+\s])?\s*::?(before|after|checkmark|details-content|file-selector-button|first-letter|first-line|selection|backdrop|placeholder(?:-shown)|picker-icon|marker|spelling-error|grammar-error|target-text)(?![a-z-])/gi;
@@ -152,6 +157,43 @@ function getStyleRulesFromSheet(
return styleRules;
}
+/**
+ * Given a style declaration and one of the properties it enumerates, returns
+ * the declaration the author wrote, or null where there is none.
+ */
+function readDeclaration(
+ style: CSSStyleDeclaration,
+ name: string,
+ doc: Document
+) {
+ let value = style.getPropertyValue(name);
+
+ if (value === "") {
+ for (const shorthand of getShorthandsFor(doc, name)) {
+ value = style.getPropertyValue(shorthand);
+ if (value !== "") {
+ name = shorthand;
+ break;
+ }
+ }
+ if (value === "") {
+ return null;
+ }
+ }
+
+ // A shorthand fills the longhands it doesn't set with `initial`, and an
+ // author can write one outright; both stand for the initial value.
+ if (value === "initial") {
+ value = (getInitialStyles(doc)[name] as string) || value;
+ }
+
+ return {
+ name,
+ value,
+ important: style.getPropertyPriority(name) === "important",
+ };
+}
+
/**
* Given a list of css rules (in specificity order) returns the properties
* applied accounting for !important values.
@@ -161,42 +203,39 @@ function getAppliedStylesForElement(
pseudo: string | null,
styles: CSSStyleDeclaration[]
) {
- let properties: { [x: string]: string } | null = null;
+ const doc = el.ownerDocument!;
const defaults = getDefaultStyles(el, pseudo);
- const seen: Set = new Set();
- const important: Set = new Set();
+ // `padding`, `padding-left` and `padding-inline-start` all write the same
+ // property, so declarations are settled per property rather than per name.
+ const winners = new Map();
- for (const style of styles) {
+ for (let rank = 0; rank < styles.length; rank++) {
+ const style = styles[rank];
for (let i = 0, len = style.length; i < len; i++) {
- let name = style[i];
- let value = style.getPropertyValue(name);
- while (value === "") {
- const dashIndex = name.lastIndexOf("-");
- if (dashIndex !== -1) {
- name = name.slice(0, dashIndex);
- value = style.getPropertyValue(name);
- } else {
- break;
- }
+ const written = readDeclaration(style, style[i], doc);
+ if (!written) {
+ continue;
}
+ const declaration: Declaration = { ...written, rank };
- if (value !== "initial" && value !== "" && value !== defaults[name]) {
- const isImportant = style.getPropertyPriority(name) === "important";
-
- if (properties) {
- if (!seen.has(name) || (isImportant && !important.has(name))) {
- properties[name] = value;
- }
- } else {
- properties = { [name]: value };
- }
-
- if (isImportant) {
- important.add(name);
+ for (const property of getWrittenProperties(el, declaration.name)) {
+ const holder = winners.get(property);
+ if (
+ !holder ||
+ holder.rank === rank ||
+ (declaration.important && !holder.important)
+ ) {
+ winners.set(property, declaration);
}
}
+ }
+ }
- seen.add(name);
+ let properties: { [x: string]: string } | null = null;
+ for (const { name, value } of new Set(winners.values())) {
+ if (value !== defaults[name] || INHERITED_PROPERTIES.has(name)) {
+ properties = properties || {};
+ properties[name] = value;
}
}
@@ -218,3 +257,11 @@ function isSupportsRule(rule: CSSRule): rule is CSSSupportsRule {
function flatten(a: T[], b: T[]): T[] {
return a.concat(b);
}
+
+interface Declaration {
+ name: string;
+ value: string;
+ important: boolean;
+ /** Position in the cascade, strongest first. */
+ rank: number;
+}
diff --git a/src/types.ts b/src/types.ts
index fe11257..5dda14b 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -13,6 +13,8 @@ export interface VisualData {
}
export interface Options {
shallow?: boolean;
+ /** Rules from `getDocumentStyleRules`, to reuse across captures. */
+ styleRules?: SelectorWithStyles[];
}
export interface SelectorWithStyles {
+ `)
+ ).toMatchInlineSnapshot(`
+ "![](\\"./cat.png\\")
"
+ `);
+});
+
+test("omits img dimensions when the attributes are absent", () => {
+ expect(
+ testHTML(`
+ ![](\\"./cat.png\\"/)
"`);
+});
+
+test("includes the candidate list of a responsive image", () => {
+ expect(
+ testHTML(`
+ 
+ `)
+ ).toMatchInlineSnapshot(`
+ "![](\\"./cat.png)
"
+ `);
+});
+
+test("keeps the href that makes an anchor a link", () => {
+ // Without it the anchor loses the user agent's link colour, underline and
+ // pointer cursor.
+ expect(
+ testHTML(`
+